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VIEWPOINT 


By Jordan Dea-MaUson 


A NeXT Victory?Ftrst Exposure 

In 1989, shortly Ixfore SLcveJobs ik NeXT launched die first NeXT 
Cube, Apple was presented with ;il least one of these brand, sinking 
new systems for the purposes of determining if any Apple intellectual 
property had been ’misappropriated” in die process of its creation. 

This strange turn of events came alx?ut due to the litigation, and its 
settlement, which Mowed Sieve Jobs in 1985 as he left Apple and 
founded NeXT, In order to settle a lawsuit against jobs, Apple demanded 
access to Ills new baby in advance of its inmteuetton for purposes of 
evaluation. The outcome of the evaluation was dial none of Apple's 
intellectual property had been misappropriated by NeXT, Steve Jobs Lind 
his new baby were “dam”. 

This exchange between Apple and its now prodigal founder had an 
interesting side effect: it gave me my first exposure to a NeXT system and 
the software ji ran. I goi 10 play with a NeXT cube as a user, and even 
did a little bit of development using veiy early versions of ProjectBuilder* 
lnterfteeBuikler, and die AppKit. It was enough of an exposure to shew 
me tlie greatness of this new platform. 

i, along with many of my eo-workers, was extremely 
impressed with the power, flexibility, elegance, and ease of 
development with the NeXTStep frameworks. A number of us, 
including myself, were very concerned that NeXT was going to 
M eat our lunch 1 " if we didn’t do something. 

No Lasting Effect 

Based on our, and oiIter's concerns, task forces were launched and 
[>eople came forward with proposals and prototypes. At its peak. Apple 
probtbly had two to three times as many folks focused on the NeXT 
Menace 1 ", as were employed in the entire NeXT engineering organisation. 

While some gcxxl came out of all this effort — for example, the 
AppleScript had its genesis in this effort - in terms of core software 
development things stayed pretty much the same. Apple made tweaks 
here and there to MPW, Think, and then Symantec, made very minor 
changes to Think C. And Metrowerks burst onto the scene and made a 
lasting impression, not by c hanging how fxxtplu developed software, but 
by turning out a fast turnaround C/C++ compiler for the PowerPC. 
Bottom line, in the realm of software development tilings w ere static, 

It WasnTJust Tools 

But tools weren't the only thing that stagnated on the Mac platform. 
In fact the entire platform stagnated. Sure, Apple moved to die PowerPC, 
and delivered Mac OS 7 and then 8, but things essentially stayed the 
same. Yes, here and there things got a little better, but no big strides 
forward were taken. Apple* but again and again new initiatives withered 
on the vine after a 1,0 was released. It was a very frustrating time to he 
an Apple employee, Mac user or Mac developer. 

Lunch Not Eaten 

Tire amazing tiling during this time was that NeXT didn’t eat Apple’s 
lunch. Yes, they uxjk some key customers and markets away from the 
Macintosh and Windows camps, but they didn’t eat anybody’s lunch, ft 


was sail to waLch, Inn a product which greatly eased the work of 
developing software went essentially nowhere. 

If you thInk about it, it was shocking, A shift in how software 
was developed — the move from procedural and static object 
oriented languages to dynamic object oriented languages like Java 

— which delivered 5 to 10 fold improvements in productivity was 
delayed for years. 

In essence, untold millions of developer hours were poured down 
a rat baity while NeXT's contributions salt on the sidelines, only seeing 
duly in a few specialized applications and narrow niches. 

A Reunion 

Fast forward now to a Friday evening in December of 1996 jusi 
prior to — as Apple always politically correctly pul it — lire “Winter 
Holiday”. Numerous me ml vis of the press and Apple's executive staff 
are gathered in Town Hall", the largest meeting room on the Apple 
Campus, for a 'big announcement”. We all know what was announced 
llial evening: the acquisition ol NeXT Software by Apple Computer* Inc, 

For me it was the beginning of a reunion with a software 
development platform that had caught my eye years previously. 
And like meeting an old love once again, il rekindled strong 
passions in me. A passion to see this great development platform 

— be it called NeXTStep, OpenStep, WebObjeets, Yellow Box, or 
Cocoa — freed from its obscurity. 

The Right Distribution 

With tins passion burning strongly, | started to ask myself, “Why did 
NeXT fail?” Why didn't a significantly better way of developing software 
make major inroads? There are a number of reasons, but the biggest was 
lack of distribution For many reasons, first because it was only on NeXT 
nil vs and later lxxau.se of pricing. NeXTStep, and later OpeaStep, had 
little discemable market penetration. 

And this is a problem that NeXTStep no longer faces! One way of 
kxrking at Mac OS X in addition to it being the long overdue overhaul 
of the Macintosh operating system — is that It is stealth distribution 
channel for NcX18tep. A w ay of getting this great development platform 
onto millions upon millions of PCs. 

Making the Move. 

I am sure that about now, you are all saying, “Ok, lifts is very 
interesting* but whai does ilvis have to do with Mac develofxrrs?" 

Ok, let me tell you what it has to do with you: you know have the 
opportunity to develop for the test personal computer around using the 
best and most productive development platform available. This might 
seem an exaggeration, but trust me it isn’t 

The launch of Mac OS X in early 200.1 is going to provide a market 
opportunity for new products and companies. An opportunity next to 
which the launch of the Power Macintosh in 1994 pales. This coupled 
with the ease and productivity provided by Cocoa is tex) gcxxl of a 
chance to pass up. 

So, what are you waiting for? 


V||iW|*OJNT 


The opinions expressed in this article are the opinions of the author, and not necessarily that of MacTech Magazine. 
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Question: Is MacHASP USB* a 
software security key or a 
sales tool? 

Answer: It's both! 

MacHASP USB is the world's first 
software protection key for the 
iMac. It gives you sophisticated 
license enforcement and compre¬ 
hensive protection against illegal 
use... in other words, real security. 

Then it gives you a big selling 
advantage. 

With MacHASP USB, you can 
license multiple software modules 
and applications. You can instantly 
unlock or upgrade them in the 
field. Plus you can freely distribute 
demos. 

Bottom line: MacHASP USB locks 
out illegal users and unlocks your 

Mac software protection provider, Micro Macro Technologies, becomes part 
of Aladdin, giving its customers even better service from the number one name. 


full sales potential - without 
getting in anyone's way. Call now 
to request a Developer’s Kit and 
our newly published guide to USB 
features and benefits. 

•For all USB-equipped Macs running an OS 
with USB support. Fully compatible with the 
ADB version of MacHASP. 
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GETTING 

STARTED 


By John C, Welch 


Networks 201 pt. 3 


Layer 1: 

The Physical Layer 


Refresh 

List time around, we covered the 
suh-OSi parts of a network model, AKA 
Layer 0, We went over the physical 
wiring, and wiring types that networks 
use. We also covered connections 
between stations on a network, the 
pinouts of Ethernet cabling, and some 
basic information on fiber optic 
connections. Finally, we went over the 
various network topologies. This month 
we move up into the actual OSl model, 
starting with Layer 1, the Physical Layer. 


is remembering its scope. In general, if it’s outside of the 
host, it's outside of the Physical Layer, anti the OSt model 
in general. This includes cabling, switches, routers and 
hubs. The usual boundary Tor the Physical Layer Is the 
connector on the NIC Part of the reason for the confusion 
over the scope of the layer is that it defines a lot of what 
the media and other Layer 0 components have to do, but 
doesn’t actually include those components. 

Since the Physical Layer transmits and receives data, let's 
look at what it lias to do for those functions. For transmission, 
the Physical Layer has to; 

* Convert the frames it receives from the Data Link Uyer 
into a stream of binary data. 

* Use the Media Access Method, as determined by the Data 
Link Layer‘s media access method. 


Laytir 1 

The Physical Layer is the foundation 
for all the other layers in the OSl stack. 
It contains all of the specifications for 
any functions that deal with die 
transmission and reception of signals. 
There are four basic functions of the 
Physical Layer: Mechanical, Electrical, 
Functional, and Procedural These cover 
all the functions that are needed for the 
transfer of electrical and / or optical 
Signals and data. Examples of these are 
signaling methods, current requirements, 
components on the Network Interface 
Gird. (NIC), and the characteristics of the 
connector on the NIC. 

One of die common problems 
with talking about the Physical Layer 


* Transmit the binary data stream serially. 

To receive data, the Physical Layer must: 

* Listen lor inbound transmissions that are addressed to a 
device attached to its host. 

* Accept correctly addressed streams 

* Pass the stream data to die Data Link Layer lor 
conversion to frames. 

One Important fact to note is that the Physical Layer 
does no error correction. It has no ability to detect errors 
in the data stream or frames it deals with. All it does is 
transfer data. 


John Welch <jwelch@aer.com> is the Mat and PC Administrator for AF.R Inc., a weather and atmospheric science company 
in Cambridge, Mass. He has over fifteen years of experience at making computers work. His specialties are figuring out ways 
to make ihe Mac do wliai nobody thinks it can, and showing that the Mac is the superior administrative platform. 
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Signal Encoding 

The Physical Layer primarily deals with gening signals in 
and nut of the host, and enaxiing and decoding them. 
Regardless of lhe type of media used, these signals are all 
electromagnetic waves of some sort Every electromagnetic 
wave has certain characteristics, the most obvious Ixrtng its 
period or frequency. The frequency of a wave is the numlxn* 
of oscillations it makes every second, No wave is a straight 
line, but rather is a regular, reasonably symmetric curve that 
most resembles a sine wave. A diagram is shown in Figure I. 



Wavelength of the signal measured in meters 


Figure L 

The symbol for wavelength is lambda, or X. Hie wavelength 
is the physical size of the signal through one complete 
oscillation, or cycle. The wavelength is also the inverse of the 
frequency. Tile frequency of a signal is the numlx.T of cycles it 
has in a given amount of time, usually one second. The 
measurement used to identify frequency is hertz, or Hz. If a 
signal has one cycle every second, its frequency is one Hz. If it 
has a thousand cycles per second, then it lias a frequency of one 
KHz, and so on. Since frequency and wavelength are inverses of 
each other, tine value of one am give you the value of the other. 
For example, the frequency of many Radar guns used by the 
police is 34GHz, or 34 billion eyeries per second. Taking the 
inverse' of this, using the I on aula 1/frequency, we get 1/34 x 109, 
or 2.9411 x lO 11, or a wavelength erf ,029411H nanometers. 
Since nanometers are billionths of a meter, this is a very small 
wave k 1 ngt h i nc feetL 

One of the more useful side effects of frequency has to do 
with the ability of a signal to transmit data. Since most encoding 
niethcxLs use the number of changes in a wave, die higlier die 
frequency, the more data that can lx transmitted by that wave. 
The disadvantage of higher frequencies Ls that the signal has less 
range and persistence. Hits is why faster IAN technologies tend 
to have less range than slower ones, (Note: I say tend to 1 here 
because when you go from copper - based LANs to fiber - optic 
based LANs, this tails apart somewhat, as a optical IAN has more 
range than a copper IAN, yet operates at much liigher 
frequencies.) If we kx)k at the signal in figure one above, you 
am see that the signal is either above or below a central point. 
The amount of distance between die top or Ixatoin most point 
in die signal, and the central point is the amplitude, or strength 
of the signal. Normally, amplitude is measured in positive or 
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No other Macintosh home automation software delivers so 
much for so tittle! 
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Unlimited power. AppleScript and voice commands provide 
users maximum customization options. 
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But. ..what do current Thinking Home users think? 


very very impressed with the user interface. Very well done. 

- Tom Carslenson 

Great product, great price. 
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negative volts, so our central [x>im is zero volts. The positive and 
negative sections of the signal are states, and the transition points 
at zero volts are the state changes. As we will see, state changes 
are critical to encoding data in a signal. There are a tew more 
parts of a wave that we need to understand, so well take a Imk 
at another wave form, the square wave, in Figure 2. 


Figure 2. 

The square wave is named lor its shape, and is a common 
wave form used in the transmission of data. The square wave is 
also useful for identifying certain parts of a wave that are used 
In signaling and encoding. The leftmost edge of the wave is the 
leading, or rising edge. The LipjXT and lowermost parts of t he 
wave are the peaks, and the middle line, where the wave is 
transitioning from a high to a low is the trailing, or falling edge. 
All pans of the wave tan f>e used in signaling and data enctxling, 
depending on which method is used. 

Regardless of the method chosen, there are three basic w ays 
to modulate a wave so as to allow it to carry' data. (In truth, these 
are the basis for many, many mom modulation techniques, and 
other trucks to get as many bits jxr cycle as possible onto a 
wave, but for our purposes, these three will do.) Hie first 
method is amplitude rntxlulntion also known as AM or ASK, for 
Amplitude Shill keying. Since the amplitude of a signal is its 
strength, the way l Ills works is suggested by the name. If the data 
being aimed by the signal is a binary 1, then the pulse amplitude 
is increased by a given amount. If the data is a binary 0 then the 
pulse amplitude is decreased by the same amount. A middle 
amplitude indicates no data. Amplitude Modulation is simple to 
implement, and widely used for voice transmission, as in AM 
radio. Due ro limitations in the modulation technique itself, ASK 
is only used for transmissions up to 1200 baud 

I he next method used is Frequency Mtx filial ion, a.k :l KM 
or FSK. This fund tons by intrcxlucing a second signal into the 
first signal. If a binary I needs to lx* transmitted, the frequency 
of the first signal is ups I lifted, or increased. If a binary 0 is being 
transmitted, the signal Frequency is downshifted, or decreased. 
If no data is Ixang transmitted, the frequency is left alone. FSK 
is more efficient and reliable than ASK, and is used for data 
rates up to 1200 baud 

The final method is known as Phase Modulation, or PSK. 
In this method, (he phase of the signal is altered to indicate a 
binary 0 or 1. If a binary 0 is sent, the phase is not altered If a 


binary 1 is sent, the phase is switched to its opposite. This 
allows one hit per shiftls) to lx sent. If more than one phase 
shift is used, then more bits can lx* sent in a set of shifts, or 
hurst, 1>SK is the most efficient, and reliable of the three 
mcxkilation techniques, allowing data rates of up to 9600 bps, 
11je.se may not seem like fast data rates, hut in combination 
with other encoding methods, (most of which we will cover in 
other articles, as they are protocol - dqxndani, and therefore 
Ixyond the scape, of the Physical Layer.), we get the data rates 
we are accustomed to on unlays lANs, 

Whichever fonn of modulation and encoding is chosen, that 
is then nxxlified by other metlxxls to allow the signal to [lack 
more bits per cycle, thereby increasing efficiency of the signal as 
a data carrier. Depending on the methexis used, anti the 
frequency of the signal, it is possible to encode anywhere from 
two to forty bits per cycle in a signal. So a cable that has a 
maximum bandwidth of 500MHz is capable of transmitting 
several gigabits of data per second. Since fiber optic' cables can 
handle much higher Frequencies than copper, it is obvious why 
filler is Ixroming more popular as a way to move the staggering 
amounts of data that a modem network is required to move. 

One* tiling to rememl^er is that any form of encoding, no 
matter how fast or efficient, imposes an overhead that subtracts 
from tlie bits a signal can carry. As an example. Gigabit Ethernet 
uses an encoding scheme known as 4B/5B. 4H/5B stales that for 
every i - bit string of data transmitted, a 5 - bit pattern is used to 
encode it. This means that 20% of I he data transmitted is overhead 
If Gigabit Ethernet were to lx* siiialy defined as 1000, or even 
1024Mbps, then the Ixst speed you ttxild actually get would be in 
the 800Mbps range- To get around this, Gigabit Ethernet is actually 
defined as 1250Mbps. so when the encoding and other overhead 
ts accounted fix. the usable speed is still very close 1 to lGbps. 

Conclusion 

It may seem that we have glossed over a lot of the 
Physical layer. Thai is partially true. Much of the Physical 
layer deals with extremely low level electrical issues that 
would lx of only academic use to the network administrators. 
Since we covered physical media in the previous article, there 
is no need 10 re-hash that here*. Also, anything that is protocol 
- specific is the property of the higher layers. The important 
thing to rememlx-r is that tire Physical layer is only concerned 
with ones and zeros, and the transfer of those things. The next 
article will deal with the Data Link layer . and the Medium 
Access Control sublayer, and that is where we will gel into 
much of the protocol specific issues of a network. 
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// 


// Like most Mac developers, 

I easily spend 12 hours a day 

// staring at line after line of C+ + code in tiny, 9 point Monaco. 

// Sometimes it makes my eyes feel (ike they’re on fire. 

I 

So the last thing I need is some 
fuzzy monitor that adds to my headaches. 

f 



/****** begin excitement *****7 

// That’s why I'm so jazzed about this SGI monitor, 

// Its ultra-high resolution = 1600 x 1024 and dpi = ito, 

// giving me razor-sharp contrast. 

// And the high refresh rate is 
// perfect for poring through lines of code. 

// At first, I was amazed at the clarity, the fine details that emerged. 

I 

It wat like teeing thinqt for the firtt time. 

I 

// Later, though, I learned to appreciate the wide aspect ratio [= i6:io|, 
// with a generous 17.3 inches of viewing area. SGI’s 1600 SW 
// lets me have all my documents viewable at once, and it's 
//a flat panel so it fits on my desk with room to spare. 


// From the moment I saw this thing I was hooked. You will be, too. 

I 

Especially when you find out 
how affordable it is. 

// * Check it out. 

/****** end excitement *****7 
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By Thurman Gillespy If I, M.D. 


Porting Command Line Interface 
Programs to the Macintosh 


How To Add a GUI to 
UNIX Programs with 
Minimal Changes to the 


The Golden Rule of Porting 

1 propose a simple golden rule of porting” Lo guide your 
porting project, 

ALTER THE SOtlRCX CODE AS LITTLE AS POSSIBLE 


CLI Source Code 


Introduction 

There is a wealth of source code 
available for the UNIX (and DOS) OS that 
uses a command line interface (CLI), 
Many of these programs have been 
ported to Windows but not to the Mac 
OS, This article describes a method for 
adding a graphic user interlace (GUI) lo a 
CLI program with minimal changes to the 
CLI source code. 

Why Port? 

Why bother lo port a UNIX program to 
the Macintosh? Mast likely, there is a specific 
program that meets the needs of your 
workgroup or interest area. However, an 
additional benefit I would like to emphasize 
is the opportunity to "brush up" on parts of 
the Mac OS API. Been lex) lazy to deal with 
Navigation Services? Never done a code 
resource or shared library? Ready to tackle a 
Carbon compliant app? Porting a CU 
program is an excellent opportunity to hone 
your skills on a small projeet that you can 
later apply to your own work. Anti do you 
tire of hearing that them is “so much more 
software available for Windows" than for 
the Macintosh? Here is one small way you 
can alleviate the discrepancy! 


At first, this rule apjxrars paradoxical* Doesn't a port from 
UNIX to Macintosh involve substantial code changes? As you will 
see, a CLI program can have a GUI added with minimal changes 
to the original source code. Furthermore, the rule Ls practical. It's 
not your code, so leave it alone! By not altering the CLI code, 
you make the porting project easier, you leave the burden of 
maintaining the CLI program with the original author and you 
make it easier to update the Macintosh version of the program 
when the CLI code is updated, 

Anatomy of a CLI Program 

Before getting started, let's briefly review the structure of a 
CU program. There are several key terms to understand; the 

standard console the standard input and output, and how 
the OS handles the command line arguments. 

The Standard Console and the Standard Input and Output 

The Standard C library assumes an interactive input and 
output environment known as the standard console. The 
standard console is typically an interactive computer screen 
where users can enter information from the keyboard and view 
output on tile screen. Many of the C library input and output 
functions can read from the standard input (input entered into 
the standard console, also known as sldin) and can write to the 
standard out put (output displayed on the standard console 
screen, also known as stdoutL The standard input and output 
are collectively referred to as ihe stdio. Functions that read and 
write to the stdio include printf, scanf, getchar, putchar and the 
C++ inserter and extractor operators « and ». Of course, the C 
library can read and write to other data streams including files 
and network connections. 


Thurman Gillespy LQ is a radiologist at the Veterans Administration Puget Sound Health Care System in Seattle, Washington, 
USA, He can be readied at rg3@u .washington.edu. 


10 


Pouting Command Link Interface Programs to mi: Macintosh 


MacTkch • Jl II,y 2000 












For example, print! writes to the standard output. Tills 
code snippet 

printf("Hello, world! \n") t 

will print the words "Hello, world!” (without the quotes) and a 
newline on the standard console (see Figure 6. below). 

The Command Line Interface 

CLI programs have a main function with the following prototype: 

int main(int argc, : bar *arBv[]); 

The compiled CLI program is invoked from the standard console 
by typing the program name and adding optional parameters 
after the name which are known as die command line 
arguments. The arguments are processed by the OS anti are 
passed to the main function as the argc and argv parameters, argc 
is the number of parameters passed to the application (plus one) 
and argv is a vector that points to an array of C strings. By 
convention, argv is structured as follows: 

Listing 1. The argv vector 

argvfQ] =■> program name 

atgv[l] => first parameter 

argv Urge Ij last parameter 

argv Urge] =^> NULL pointer 

Every command line argument separated by white space is 
parsed into a separate argv string. Fur example, here is how the 
command line arguments for a program named midiZabc are 
translated into argc and argv. 



Fire Up Your Mac 




* % * 


USB FireWtre 
Hard Drive 


Mac users can enjoy the 
freedom of transferring 
and storing their data 
| quickly and easily 
with VST's line of 
FireWire and USB 
•*. peripherals, 

VSTs FireWire 
products, such 
as the ultra slim 
Hard Drives, Zip 
Drives and the new 
FireWire RAID Arrays 
provide the ultimate 
in portable, high-speed 
data transfer and storage 
solutions wherever you go. 


A must have for all Mac users in today's digital age is the 
versatile USB Tri-Media Reader, a 3-in-1 multi-media device 
capable of reading and writing to floppy disks, SmartMedia 
and CompactFlash, Or, if you're just looking to transfer small 
files quickly and easily, the stylish USB Floppy Drive with 
Color Kit is the perfect match. 


For the best of both worlds, VST's ultra slim FireWire/USB 
Combo Hard Drives provide up to 30GB of high-speed FireWire 
and USB connectivity all in one tiny 3 U x 5" package that's small 
enough to fit in your shirt pocket. And with the USB CD-RAA4 
that comes complete with an integrated rechargeable battery 
and an optional FireWire cable, you can burn CD's anywhere. 


Listing 2. Converting command line arguments to argc 
and argv 

// invoking the pn>gram from rhr console 

midi2abc -f mytune.midi u 2 


Whatever your high-performance storage needs might be, 
VST has the solutions for you. So visit www.vsttech.com to 
learn more about these and other exciting products designed 
to simplify the digital lifestyle. 


// anti argv 

argc = 5 

argv[0j , 'midi2abc“ 

argv11 j —> *-r 

argv 12] “> "mytune. re I d i " 

argv f 31 " a" 

argv[4] —> *2* 

argvb] => NULL 


Project Overview 

To port the CLI code with as few changes as possible* we 
want our project separated into two components: a Macintosh 
GUI “front end* program that passes the argc and argv 
parameters to a separate component that contains the CU axle. 
We accomplish this separation by compiling the CLI code as a 
code resource or shared library ihai is called by the Macintosh 
GUT program. In addition, we need glue code Lo handle the C 
standard library functions that read and write to the stdio. A 
diagram of the technique is shown in Figure 1. 
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Figure I: Porting overvieiv 


This porting method will work best on UNIX programs with 
well defined input and output that are typically invoked from the 
command line. 

Define the Objectives 

Alter you've Identified the code to he ported, sketch out 
your objectives txTure getting started. Here are some points you 
should consider. 

* What is the purpose of the ported program? 

* Who is the Large! audience? 

* What is the basic GUI interface? 

* What are the target platforms? (MacOS X, 68k. CFM6Bk, etc.) 

* What can I learn from this project? 

General Porting Issues 

There are some general issues to consider when porting 
from one computer platform to another, even if the OS is 
unchanged. Mac programmers had to deal with many of these 
issues during tile conversion from 680x0 to PPG. Some of these 


porting issues include the following. 

■ die size of in! 

• bitfields (notoriously non portable) 

• little endian vs. big endian byte order 

• data alignment 

• exact byte layout of structures 

• implicit type conversion 

• C/C++ language extensions 

• library functions not supported by MSI. 

For a thorough discussion on these issues, read the 
white paper published by Metrowerks on porting GNU C 
programs to Code Warrior (Thompson 1999) which is 
included on the Code Warrior CD. Correcting these general 
porting issues may require significant code changes. This 
article focuses on the changes necessary to add a Macintosh 
GUI to your command line program. 

Steps in die Process 

After your target code and project objectives have been 
identified, here is a sequence of steps you can take to port your 
CM program. 

» Step l; Do a minimal Mac port dial preserves the command 
line interface. Understand this program and validate tire 
output, if any. Identify the tools for developing the Mac: GUI 
front end. 



Think about it 

Why should you 
have to buy a 
USB hub, then hang 
stuff off of It until it 
looks like something 
out of Edward 
Scissorhandsl 
Why fumble around 
under your desk 
every time you want to 
plug in another device? 
Instead, try tills. 
A modular, stacking system 
of USB hubs, with adapters 
for serial and SCSI. 
Neat Compact. 
And, oh yeah.,, 
drop dead gorgeous. 


Belkin Comp on eats 
Compton ■ CA* USA 

310.898.1100 ■ Fax 310, B9B.1111 
United Kingdom * Holland * Atlanta, GA 
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Yellow Dog Linux Champion Server " 
by Terra Soft Solutions, Inc. 

Dedicated to Apple Computer, Terra Soft Solutions maintains the largest 
and most experienced PowerPC Linux development staff in the world. 
Enjoy this mature, proven, and professional Linux distribution. 

In addition to the expected Linux applications and utilities 
Yellow Dog now includes Mac-On-Linux which runs 
the Mac OS inside of Linux at near native speeds, and 
"yupl”, our famous automated system update utility. 


Available on 3 CDs or pre-installed on hard drives. 
Includes bootable Install & Rescue CDs and all source RPMs. 

60 days installation support available. 
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* Step Build a code resource or shared library from the 
CL1 code. 

* Step 3: Build the Mac GUI front end. 

* Step 4: Put it all together. 

An Example CLI Program Port 

I recently ported a UNIX program that converts midi files to 
a I xl format. ABC format is a human readable music notation that is 
an increasingly popular method of exchanging music over the 
internet, III use* Ms project to illustrate the techniques in this article. 

ABC 

<http://www.gre.ac.uk/'-c.walshaw/abc/> 

The target source code is midi2abc t written by James 
Allwright. The project has been ported to Windows, but only a 
bare bones Macintosh purl had been done, 

midiZabc 

<http://perun,hscs.wmin.ac,u!d-jra/abcMIDI/> 

Here were my project objectives (which changed slightly 
during the project). 

• Purpose: convert midi files to a be format. 

• Audience: owners of midi files who wish to convert them to 
abc notation. Many have older Macintoshes. 

• Interface: convert files from application, or by dropping files 
on application icon from desktop; convert one nr more files, 
or folder full of files; converted output displayed in text 
window, w ritten to a file, or both; floating dialog to easily set 
the conversion parameters. 

• Target platforms: Mac OS X (eventually), PPG and 68k 
Macintoshes w'ith System 7 or higher; support Navigation 
Services if available. 

* Personal goals: learn NavServic.es API; improve preference 
file handling; learn code resource technology. 

The name of the ported program is MacMIDIZubc (Figure 2). 

MacMIDI2abc 

<http://www.dr-razz.com/midi2abc/> 

MIDK 

<p> 

MaclifDl2abc 

Figure 2: MacMID12abc application icon 

The CLI Port Demo Program 

1 found it was useful to first port a very simple UNIX 
program that printed the command line arguments to stdout 


(Listing 3). The source code and Code Warrior project files for 
this demo program are available on the MacTeeh web site, and 
I suggest you refer to these files when reviewing this article. 

Listing 3- cl_echo.c 

// a simple: utility tkii prints at#: ond oygv to sldout 
// it also dieefcs that argvUrgc] =- NI LL 

#ir.clude <stdlib.h> 

^include <stdio,h> 


main 

int maindtjt arge. char *argvtJ ] 

( 

int i: 

printfCharge: %d\rC, arge): 

for (i “0; i < arge: i++) 

printf{“argvLXdf: i, argv[i]); 

if (argv[srgcl **=* NULL! 

prinif("argvfargc] — KtFlXW) I 
else 

printf("error: argv[argcl lfl not NULL!\n"): 
exit CO): 


Step 1; Macintosh Minimal CLI Por i 

Early in the project, I recommend a minimal Macintosh 
port that preserves the command line interface. The minimal 
CLI port will help you focus on ihc non-GUI aspects of the 
project, and helps prevent wasting time cm the GUI code if 
the CU code can't be ported, 

CodeWarrior SIOUX Console 

CodeWarrior provides the SIOUX (Simple Input and Output 
User exchange) facility which creates a standard console 
window in a Macintosh GUI application. Here are the steps to 
create a SIOUX console project. 

■ Create a new r CodeWarrior project with the MacGS C/C++ 
stationary ( Figure 3). 



Figure J Selecting MacOS C/C++ stationary* 
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V Scripting Saves Time - InstallerMaker 
provides full scriprability for all features, 
Automating the build process saves rime 
and helps ensure the integrity of your installer. 


Trialware in Minutes - Creating trialware is a 
breeze with InstallerMaker: With just a few ^ 
dicks, and no extra coding, you can create M 
trialware that is e-commerce ready. 


Update in a Flash - Easily build intelligent 
"diff files in installers to create small updaters for quick 
online distribution. From one simple installer, you can 
update 68k, PowerPC or FAT applications. 


More Details Online - There's a lot more 
InstallerMaker can do for you. Get ail the 
info at www.aladdinsysxom. 


Aladdin 

[Systems 
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> Get n Together 
With InstallerMaker 


Installation 
From FTP or 
HTTP Sites 


When Time is Money, Get it Done Fast! 

Build Smaller Installers - With Stufflt InstallerMaker, you'll build installers 
faster than ever before! Compress your installers an average of 15% smaller 
using the power of the Stufflt Engine 1 . Smaller installers download faster, 
provide added space on CDs and servers, and increase network bandwidth. 

Quickly Create Demoware - Easily turn your application into a polished 
demo, just set the number of days for the demo to be active, paste in the 
graphics, and you're done! 

Archive Freshening - Automatically update your installer project file; 
eliminate repeated searches for modified files. 


• Resource 
Installation 


ShrinkWrap 
Disk Image 
Support 


• Hierarchical 
Package 
Support 


• Built-In 
Updaters 








Laptop Storage Cart 

for the iBook! 


Set the project stationery for Lhe appropriate 
Standard Console (Figure 4), I use Sid C Console 
PPG for starters. CodeWairior then sets up a projet a 
ready tor a .standard console application (Figure 
5), and includes the correct SIOUX libraries. 


Looking for a safe, secure place for your iBooks? Store, move 
and charge your iBooks with this new Cart from Anthro! 




Compact Secure locking 
and mobile! hardware! 



Handles to Holds up to 

push or pull! 20 iBooks* 



Vents for 
airflow! 



Ex ten ml power Place for A C 

and telephone Power Adapter 

outletsI and cordsf 



Room for 
AirPorts 
on top I 



Wrap your Btg wheels go 

cables neatly / 



Tour Anthro World at our 
eye-opening web site. 

www.anthro.com 

or cal! us ar 800-325-3841 

6 00 AM to 6 00 PM PSl M-+ 

& 

ANTI-RO 



Figure 4: Selecting standard console stationery 


My Cl I Portjntp 


:0S 



f. filwi. O U 


Figure 5: Vc/r fmtjecl for standard console 


• Include the source f ilers for the project. If there are 
multiple source files and you are uncertain which 
ones to include, begin with the file that contains 
the main Function. 

• Add the ccommand function to the main statement 
j usl I>elt >w the It jeaI v:u i;i hie <lecI;iroi it >ns and incl l ide 
the console-h and SIOUX.h (leaders (listing 4). 


Listing 4, Adding the ccommand function to main 

Jf include <SI0tlX.b> 

4 Inc hide <corn»rt le .H> 

int pain(int arge* char *argvn) 
t 

// kic.il variable defined here 

// add tills smiauciu alter Incut variable ami 

}f ^before anything dsc 

arge = ceammandUargv); 


Anthro Corporation® Technology Furniture 1 ® Since 1984 
iBook is a registered trademark of Apple* CorjmrMinn 


























































* Compile the projec t. Use the compiler and linker errors to 
guide changes to the included header files and project source 
files. Common header files that need to he included are 
<stdl*b*h>. <$tdio.h> and <$tring + h>. 

• Handle any general porting issues such as byte order, size ol 
tnt, bit fields, etc* 

When completed, you have a Macintosh application ready 
to accept command line arguments just like the UNIX version. 
All stdio is routed to the SIOUX console window (Figure 6). At 
this point; make sure you have made as tew changes to the 
source code as possible in order to support the minimal port. 


Hello, wo rid .out 

H 

Hello, war Id 1 

* 






Figure 6l* The SIOFX console window 


The ccommand function 

The ccommand (unction displays a dialog with a text field 
for entering the command line arguments (Figure 7). There are 
also radio buttons for redireeling the standard input and output 
to a file or the standard console, When the dialog is closed, the 
arge and argv variables are correctly configured. 



Understanding the application 

After compiling the SIOUX console application, lie certain 
you understand all the command line arguments anti their effect 
on any output. Are there certain combinations of arguments that 
are allowed or make sense? Also try' to understand how users 
will typically use the program. 

For my midi2abe port, I spent an afternoon with a musician 
friend who had midi files fie needed to convert to alx format. 
We played with all the parameters, and tried to understand their 
affect on the abc output. Key concepts 1 learned from this 
session were that converting midi files was likely to be iterative, 
and that it was desirable to save the conversion parameters from 
one session to the next. 
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Validating the Output 

[f the CU program produces an output, try to validate the 
output. In my midi2abc port, we viewed and played the abc 
output in liarFly. a Macintosh abc viewer and player. The abc 
files appeared to play correctly, A more rigorous session would 
have compared the Macintosh abc output with the output from 
the original UNIX program. 

BarFly 

<http://rbu01.ed-rbujiirc.ac.uk/BarFlyStuff/BarFlyPagehtml> 

Identify Tools for the GUI 

By this time, you should have selected the tools you will 
need to produce the Mae GUI front end Most likely, this will lie 
the application framework or development system you currently 
use. If your program processes files, make sure you have good 
support for opening or convening files and folders dropped on 
the application icon from die desktop. 

For MacMIDI2abc t I chose ToolsPlus for the GUI 
development because I am most familiar with that environment 
and it met my requirements (Gillespy 1999). 

ToolsPlus 

<http://www.interlog.com/~wateredg/> 

Sup 2: Build the Cool Resource 

For die next step in our project, we need to compile die ClJ 
code as a code resource or shared library without the SIOUX 
console. For the midi2abc port. I chose to use a code resource 
because code resources work with 68k Macintoshes without the 
Code Fragment Manager. The remainder of this article will only 
discuss code resources. 

Create a new empty project. If you are supporting 68k and 
PPC code resources, create a second target and name each target 
appropriately, For an example of the correct project settings, see 
the CU Port Demo project. 

Ups on Dealing With Code Resources 

There are two aspects to programming with axle resources: 
the source code and the project settings. The source code is 
reasonably straightforward, but getting the project sellings 
correct can be frustrating, After reading joe Zobqiw’s classic 
lxx>k on code resources and shared libraries (Zobqtw 1995), I 
found the private axle resource examples included with 
Metrowerks CodeWarrior to \k extremely helpful. 

CodeWarrior Pro 5:CodeWarrior Examples:Hac US Examples: Code 
Resource Examples:Private Resources: 

Here are a few problem areas to check carefully. 

* correctly exporting and linking with symbols. 

* getting the initialization, main and termination entry points 
correct. 

* correctly setting die resource header, 

* correctly setting the file name, resource name, resource type 
and resource ID. 


Resource Initialization, Main and 
Termination Entry Points 

In the PPC linker Target Settings Panel, there are fields for 
Initialization, Main and Termination entry points (Figure 8). 


Entry Points 

Initialization 

Main: 


Ter mi nation: ; i r.-ii n-jt.-L l ■ ] 


Figure 8; Entry Points (PPC linker panel setting) 

The Main entry point is, of course, the main routine of Lhe CU 
axle If you enter lhe name of the initialization and termination 
routines in the entry poinL fields, these routines will be allied 
automatically when the code resource is loaded and unloaded. 

However, the initialization routine has important work to 
perform since we don’t want it) change the CU code main 
routine. The initialization routine must import any symbols from 
the GUT application that the resource requires. If the symbol 
import fails, calling the code resource will also fail. Therefore, 
for MacMIDI2abc I chose to manually call the initialization 
routine from the GUI code, and check an error resell for failure. 
If you manually call the initialization or termination routine, then 
leave the respective fields in lhe sellings panel blank (Figure 8c 

Handling Standard Input and Output 
without die SIOUX Console 

There Ls a common misconception that you can't use Standard 
C library functions that use the stdio in a axle resource. However, 
supporting the C library stdio without the SIOIJX console is easy 
in either a Macintosh application or code resource. Instead of the 
SIOUX libraries, add a copy of the Metrowerks file console.stubs.c 
to die axle resource (or application) project. Then remove the 
ccommand function and included consoled and SIOUX, h files front 
the CLI code if you added them for lhe basic CU port, and donT 
include the MSL SIOUX library, 

CodeWarrior Pro h :Metrowerks CodeWarrior;MSL:MSL_C: 

MSL_MiicGS:3rc:console.stubs.c 

The con sole, stubs.c file provides four stub functions dial 
allow you to intercept calls lo die stdio. You can use these 
functions to create your own custom standard console, or to 
route the stdio as needed for your project. 

Listing 5. Console stubs prototypes (console.stubs.h) 

short InstallConsolsCshort fd); 
void ReTnoveCorisolp(void): 

long WriteCharsToCoirieoltdrhdr ‘buffer, long ft); 
long ReadCbarsFromConsoltf (char ‘buffer, long n); 

Before any reading or writing to the stdio, InstaliConscle ts 
called. Then any function dial w r rites to the standard console 
(e + g. t print!) calls WriteCharsToConsole, and any function that reads 
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from the standard console (e.g., scan!) calls 
ReadCharsFromConsole, Finally. RemoveConsole is allied If you 
are not creating a custom standard console, the InstailConsole and 
RemoveConsole functions can lie left empty. 

After including a local copy of console.stable in the rode 
resource project, we need to connect the sidio in the code 
resource to the GUI application. Here are the steps to 
accomplish this task: 

• in the Mac GUI program, create one or more functions that 
will route the stdio 

* in the code resource, create function pointers that match Lite 
GUI functions 

* link the pointers to the GUT functions when the resource is 
initialized 

• call the function pointers in the WriteCharsToConsole and 
ReadCharsFromConsole routines 

In midi2a()c t the abc output is written to the standard output 
via multiple printf calls. In the Mat' GUI application, I wrote a 
function - CopyBylesToSuffer that copies n bytes to a buffer. The 
CopyBytesToBuffer function keeps track of how many bytes are 
in the buffer and prevents buffer overflow. From die buffer, the 
alx output can lie redirected to a text window, a file or both. 
See the CU Port Demo sample code for an example of the 
CopyBytesToBuffer routine. 

long CopyBytesToBuffer {chat 'bytes. long mimByLcs); 


In llie code resource project, 1 created a function jxrinter to link 
with the CopyBytesToBuffer routine. Note that the prototypes of die 
CopyBytesToBuffer function and the function pointer must match 

typedef long [‘CopyBytesProcFtr)(char *, long}; 

CopyBytesProcPtr CapybytosProc ■* NULL: 

Then FindSymbol is used to link the function pointer with 
the imported CopyBytesToBuffer symbol when the code 
resource is initialized. The complete details of symbol linking 
are described below. 

FindSymbo l (connTD, ** V pCopyBytesToBuf ±e c " . 

{Ftr U&CopyByLesProc. ^yuiClass} ; 

Finally, a call to CopyBytesProc within the 
WriteCharsToConsole routine will redirect output written to the 
standard output to the buffer in the GUI application (Listing 6). 

Listing 6. Redirecting the standard output 
(console, stubs.e) 

typedaf long (‘CopyBytesProcPtr) { char *, long): 

CopyBytesProcPtrCopyBytesProc *= NULL: 

Writd jurat* j< junsulc 

long WrilcCharsToCofisoletchar 'buffer, long n) 
f 

long bytesWrilLen; 

bytesVritten = (‘CopyBytesProc)Ibuffer, n): 
return (bytesWritten): 

I 
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When does output written to die standard output actually 
show up in WriteCharsToConsole:' The details are implementation 
Specific, but the output is usually flushed at every new line or 
when the standard output buffer is full. Normally, the exit routine 
will flush the stdio and guarantee ail input and output is properly 
handled at program termination. However, if we have overridden 
the exit function (see below), some bytes might he left in the .stdio 
buffers. I handle this possibility by calling fffush in the program 
termination routine (listing 12), 

Linking with the Mac GUI Application 

For FPC and CFM68k code resources, you want to export 
any symbols that the GI il needs to call, and you must import any 
symbols from the GUI that the code resource needs, To export 
the functions from your code resource that will lx 1 called by the 
GUI program, define routine descriptors for the routines. Here is 
how to define a routine descriptor named mainRD for the code 
resource main routine, 


Code Fragment Manager (CFM) within the code resource. Ifs a 
three step process. 

• use GetProcessInformation to gel the FSSpec of the GUI program 

• call GetDiskFragment to get a connection TO to the application. 

• call FirxfSymbol lo attach the imported symbol with the correct 
(unction pointer. 

In order to minimize changes to the CL] code, this code 
should be in the code resource initialization routine. Write Lite 
initialization (and termination) routines in a separate file, and 
include the file in the code resource project. T included these 
routines in a file named CR.glue.c. 

listing 8, The code resource initialization routine 
(CR.glue.c) 

typedef long ("Copy&ytesProcFtrHchar *, long) ; 

CppyEyresProcPtr CopyBytesProc = NULL; 


Listing 7. Defining a routine descriptor 
for the main routine 

1 nL mairriint arge* char *argvfll; 
enum [ 

uppKain£ntryPrnrIiifn “ kCStackBascd 

REStJLT_STZE(SI 3 yiLCaDEtei^eaf (int ))) 

STACK„RaUTlN!LFAKAHETSR(t. SIZE COPEUi»euf(int))) 
STACK_H0UTI HE _PARAHETER f 2 , SIZE C0!)E{ 

sizeof (char **))) 


RoutineDescriptor raa i nRf> = 

BUtLD ROirrrNE^DESCRXPmR(uppKalnEntryProctnf n . main); 

Then export the mainRD symlx>l so it ran be linked from the 
GUI program. The easiest method of exporting symbols is to use 
the Export linker function. Select the Use ".exp 11 file option from the 
Export drop menu in the PPG PEF Target Selling panel (Figure 9) 


Export [ Use “ exp” file t\ 

Figure 9: Exf>ort symM sating 

The next time your code resource is built, the compiler will 
generate an \exp’ file that contains ALL the symbols in your 
code resource. Delete all the exported symbols and add only the 
routine descriptor name(s) you want exported. For the example 
above, the only entry in the .exp file would lx' mainRD. Then 
include the .exp file in die code resource project. 

Don’t forget to edit the .exp file! Otherwise, your resource 
will suffer enormous code bloat, and you will likely encounter 
linker errors. A mistake I made several times was to add Lite name 
of the routine in the .exp file instead of the routine descriptor And 
don't forget to add the ,exp file to the code resource project, or 
the FindSymbol call in the GUI application will fail 

To import symbols from the GUI program, you use die 


iniiu3i&nh>n routine fur PPL and CFMftBk crxlc fesotircc 
il!uMr.[to how to link (he <k»py BytcsProc function pointer with the 
CopyByiesTbBufter routine in ihi- GUI code 


OSErr MyTnltCR(void) 

1 

P metis u St* r i a INumbe r 

ESSpec 

ProcessInfoRec. 
CFraftCannact lon!3) 

sum 

CF rn gS y mb o I Gla s s 

Prr 

OSErr 


PSth 

BiyFSSpPc; 

haliio; 

tnfuRec; 

ctmnlB; 

errName: 
symClass: 
mainAddr; 

#rr; 


MyJiiitCR 


// iim. GclPruccssIntomiatkm to gel the FSSpcc of our app 

infoRec.procgnsIfiraLeiigth = sizeof{Process!nfoR^r); 
infoRec.prcccssNawe = name; 
infoRcc.prucessAppSpec - imyFSSpec; 

PSN.higbLongOfPSN - 0; 

PSNDowLoagOfPSN * kCur rent Process: 

err - Get Process T n formal ion( &PSN. fcinfoRec]; 
if {ert != noErr) 
return err; 

// (MiOiskhrjgmciu will alum Uic cunnll) number nettled fur subsequent 
// culls ID l : mdSyral)o] 

// li will a\so return she address ot main in ihc native App (which we ignore) 

err - GotDiekFragiwtii (iufuRoc .processAppSpec* GL, OL. 

Info Roc .pro c c ssN ame. kload CF ra g, kcoiin ID t 
(Ptr*)&niainA4dr, errNaige); 
if (err t- uoEti) 
rot urn (?rr; 

urr - FindSymbol(connED* "VpCopyBytesToBuffer w t 
(Ptr *)&CopyByt geP roc * &sy&Clnss); 

roturn err; 


If MylnitCR succeeds, then the CopyBytesProc function 
pointer redirects output written to the standard output to die 
GUI application (Listing 6X 


Dealing with Memory locales 

CU programs rail malloc (or new) to allocate memory. The 
default malloc implementation in the MSI allocates a chunk of 
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memory at the first memory request (generally 64k), and then 
suballocates the buffer as needed. In previous versions of M5L. 
this huffer was not freed when all of the suballocations were 
freed, which resulted in a memory leak for code resources and 
shared libraries. In Ccxle Warrior Pro 5 r the problem is fixed: 
when a malloc buffer Is no longer in use, it is freed and returned 
to the operating system. 

However, your ported code may leak memory, i,e., not all 
allocated memory is freed before the program exits. Rather than 
attempting to fix the memory leak in the CXI code (remember 
the golden rule of porting), you can manually free the malloc 
buffer after the CLI code is finished, Metrowcrks provides a 
somewhat dated Ole, GetmemWithFree.c, that tracks the malloc 
buffer allocations and allows you to manually free the buffers 
with the FreeAl I Malloc Memory function, 

CadeWarrior Examples: MacOS Examples: Code. Resource 
Examples: CW Code Resource Info: Memory Emblems 
in CRs: FreeAllJialiocMemory:_GetnieinWiLhirree,C 

However, there are two changes you have to make in this 
file for this facility to work the current version of MSL The 
function Getmem needs to be renamed _sys_alloc, and the 
pooLalloc.h header must lie Included (Listing 9). 


Listing 9- Changes lo _GetmemWitliFree.c 

^include <po©l_a]1oc.h> // add this header 
void *_f!ys_alloc{size_t size) // rename _Gcimcm to sys_allix 
void *pr 

Slze_t isize = size; 

it isize <= 0 ]| I(p = NewPtr(isize))) 
return OL; 

PutInMallocUst( (Ptr)p); 
return p; 

I 

After changing your local copy of jGetmemWithFree.c, add the 
hie to your code resource project In the code resource termination 
routine call FreeAlIMallocMemory to free all the malloc buffers, I 
used this technique to handle a memory leak in midiZalx:. 

Handling exilQ 

ANSI C programs commonly use the exit function to 
immediately abort a program if an unrecoverable error occurs. 
Unfortunately, exit aborts both the axle resource and our 
Macintosh GUT application! 

You can handle tills situation by overriding the exit routine and 
using the setjmp and longjmp C facility, setjmp and longjmp provide a 
“non-local goto" that permits returning to a defined point set by 
setjmp from anywhere else in the application. 

To use setjmp and longjmp, first define a global jmp_buf 
variable in the file that contains the main function. Then call 
setjmp early in the main routine (Listing 10X 

Listing 10* Using setjmp and longjmp 

#include <setjap.h) 
ayjuffipbuf; 

lnt maiJitiut arge, char ‘argvf)) 

// ItxaJ variables declared hm- 

volatile.* int val: 

if (val - setjiffptiiiyjmnpbuf)) I 
return (val - 1); 

1 

// typical error handling 

p = tnalloc(nbytes); 
if (p — MULL) I 

fpriutf(stderr. 'Malloc failed !\n"h 
exit(l): // abnormal termination 

I 

exit (0): // normal termination 
J 

The first lime setjmp is called, it initializes the jmpjiuf variable 
and reaims 0. Subsequent calls to longjmp returns program control 
to setjmp, which now returns a non-zero value. Since automatic 
variables are nor guaranteed to be valid when program control 
returns to setjmp, 1 use the volatile qualifier with the val variable. 

Next, override (redefine) the exit function and call longjmp 
within exit. 1 wrote my new exit routine in a file named exit glue,c, 
and included this file in the code resource project. 
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Listing 11. exiLghiex 

// see Listing Hi for tniiiilixing jmp buf 

^include <stdlib.h> 

exit 

lx_ + certain set jmp is culled before lon^jinp 

void exit tint status) 

( 

extern myjunpbuf; 

longjmp(myjumpbuf, status + I); 

) 

When the project Is compiled, the linker will complain of 
duplicate definitions of exit* tfhich you can ignore. 

Link Warning : ignored 'exit' (code) in M5L C.PPC.Lib 
Previously defined in exit.glur.c 

By convention, exit is called with a 0 for a normal 
termination, anti a I for an abnormal program termination. 
However, longjmp cannot be called with a 0 for the status 
parameter. Thus, 1 add 1 to the status parameter and then 
subtract 1 from the return value of setjmp. These steps ensure 
that exrt(O) returns 0 and exrt( 1) return 1 when the CLI main 
routine exits (listing 10 and 11). 

There are many hazards u> using setjmp and longjmp. Head 
the Code Warrior documentation for further details. 

The Termination Routine 

In midi2abc 1 1 use the code resource termination routine to 
manually clear the malloc buffer (since there is a memory leak in 
the midi2abc code), anil to Bush the sldio buffers (since 1 
override the exit function). 

Listing 12* The code resource termination routine 
(CR.ghiex) 

MyTcrmiimtcCR 

void MyTerminat eCR £ void J 

I 

// dear the stdio buffers 

fflush(NULL); 

// manually purge tlie mailin' buffer 

FreeAl IttalIccMemory (}: 

I 


68k Code Resources and Global Data 

In tlie 68k runtime architecture, global data is referenced from 
the A5 register. Code resources must use another method of 
accessing their global data. Ok It: Warrior uses the A4 register, and 
requires the following changes to your project* First, the appropriate 
A4 libraries must lx* used in the axle resource project* Second, tlie 
EnterCodeResource and ExitCodeResource macros must be used to 
properly set up the A4 register (see Listing 13. below)* 

Supporting 68k Macintoshes without the CFM 

The Code Fragment Manager (CFM) method of accessing 
symbols described above will also work with 68k Macs if the 
CFM is present. CFM for 68k Macintoshes (CFM68k) is available 
on Mac OS 7.1 and higher. 


Cross-Platform C++ 

PP2MFC puts your 
PowerPlant 
applications on 
Windows 3 

www.oofile.com.au 


If you want to support 68k Macintoshes without the CFM, 
you have to use another method of importing symbols from the 
GUI application. There are a number of options available. We 
could add one or more parameters to tlie main entry, and use 
them to pass tlie GUT symbols to the 68k code resource. We 
could also use a “parameter block" similar in a Photoshop plugin. 

For MacMlDI2ahc» 1 chose to overload the arge and argv 
parameters (Listing 13)* Since arge cannot be less than 1, I use 
arge values of zero or less as hags. An arge value of 0 is a signal 
to call the code resource termination routine (Listing 12) T and a 
negative value is a signal that the argv parameter contains die 
address of a routine being passed to the resource. 

Listing 13* 68k code resource without CFM 

//CU code 

int main(ini arge, char *acgv(]) 

I 

// local variables here 

Ktu crCodeltesaurcen : 

if (arge 0) I 

MyCK68k(argc * argv ): 

ExitCodeResource(); 
return 0; 

I 


ExitCodeResourcef): 
return 0; 

) 

ll t^Tgluc.c ____ _ 

MyCR68k 

how m initiative und [erminate a (>Nk code resource without CFM 
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void MyCR68k(inr arge, void *argv) 

switch (arge) t 
case Qi 

//call ihe Xrminaitoii nuuimc (listing 12) 

MyTerminateCftC): 
break; 
ease -1: 

// link (>)pyRvtesTofklfftT address with the function |Xj-irtlt:r 

Copy By t efiProc ~ (CopyBytesProc)argv: 
break: 

i 

} 


Step 3: Build the GUI Program 

The GUI u front end - ' program is responsible for handling 
window, menu and file operations, and for converting user 
interface elements into arge and argv parameters that are passed 
to the axle resource. This is the creative part of the project that 
gives you an opportunity to demonstrate your user interface and 
program design skills. 

Converting command line arguments to a GUI 

Typically, you will design a dialog that has button, menus, 
rexr fields and other user interface elements that reflect the 
original command line parameters. As an example, here is the 
"usage" output from the midi2abe program (reformatted slightly). 

Listing 14* midiiabc usage output 

iuidi2abc version 2,0,8 
usage : 

midi2abc <opttfwn> 

-a <heatn in aruicruiiis) 

xa extend iiiiserusis from file {find firm utrgtig note) 
ga gueaa anacrusis (minimize ties across bars) 
in <time signature> 
xm extract time signature from file 
-xl extract absolute note lengths iroin file 
T b <bars wanted In output) 

■0 <tempo Sn qunrlet notes per minute) 
k <key signature) -6 to 6 sharps 
-c <channel) 
f <inptit file) 

Only the £ option Is compulsory, Use only one of xl. 
b and 0, If none of these is piesent, the program 
attempts to guess 13 syllable note length. 

From this list and my knowledge of ihe midi2abc 
program, I created 5 user interface groups and ranked them 
in order of importance, 

* Time Signature 

* Key Signature 

* Channel 

* Tempo 

* Anacrusis 

From these groups, I designed a single floating dialog that 
allowed the user to select the conversion parameters (Figure 10). 
Ihe dialog also allowed the conversion parameters to lie saved 
to disk in the Preferences Folder. 



Figure I ft Mac MU)I2ahc Settings dialog 

I land ling arge and argv 

For MacMIDliabc, the must complicated portion of die GUI 
code is the conversion of the Settings dialog slate into arge and argv 
parameters to lie passed In the axle resource. I lere is an overview 
of the data structures and routines that I developed for tills task. 

* a command data structure tCMD 0 that contains the arge and 
argv parameters, anil relit red support functions 

* a custom settings resource (setg) and matching data structure 
f SETTINGS JDLG J) that reflects the slate of the Settings 
dialog 

* a routine for converting the settings data structure 
(SETTINGS^,DL.GJ) into the proper arge and argv parameters 
within the CMDJ struc ture 

The first data structure to consider is ihe CMDJ structure, 
which contains the arge and argv parameters. 

Listing 15* The CMDJ structure 

emim t 

kNtJM_MGS - 20, tftnax #oftrgs 
kARG_STRLEN = 20, // nigimunl siring length 

kFNAME LEN ■ 23 B ff tile name siring length 

// argument valor (array of 1 elute) 

Iypedef char *ARGV_tfkNUM ARCS): 

// array of C stringb for arg* (except file dame) 

typedef char ARGLIST_t IkNUH^AKUS] [kA«G_STRLENl ■ 

U file name is special cast (allow for MacOS X) 
typedef char FNAME_i [ld'NAH£_LEfi|: 

// command line (arge, argv) 

typedef struct cmtLs I 
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s hor t a r gc; // number of arguments 

ARGV t argv; // vector to argument list 

ARGLIST ! yrglist: // array of C strings for args 

FMAME_t Enamel ttfite name 

I CJtD_j. *CMD h; 

In MacMlDI2atx I use data hiding for the significant dam 
structures. The double underscore notation (CMD_t) denotes the 
hidden type, while the single underscore notation (CMD_t) denotes 
the public, incomplete definition. For simplicity, I will use the 
public definitions of the structures in die text of this article. 

At program startup, I allocate and initialize the CMDJ 
structure, and set argv[0] to the program name (Listing 16). 


Listing 16. Creating a new argument list (CMIM) data 
structure 

NewAigLisi 

allocate memory and initialize new CMDJ 
application responsible for storing result 
accepts: address of CMD_i pointer <must be Mill) 
name of program 

returns: error code, address of new CMP i 

OSErr NevArgList(CKD_p t *cmd* char 'prog^uame) 

long i* len; 

if (*emd != NULL) 
return 1; 

*cnid " (CMD_p_t)NewPtr (si^eof (CMD_t)); 
if ( 4 cmd — NULL) 
return iMemFul lErr; 

t'rmd) >argc = 1; 

P set and dear the argv vector 7 

for (i - 0: i < kNUM ARGS; 1++) I 

(*cmd)'>tr&li£t[i] 10) ■* *\ O': f *empty string */ 

(*cmd) >argv[l] - M('cmd) >arglist[iJfQl); 

1 

r clear the ftk* name 7 

{VjndJ >fnartie(0| - *V0J 

T copy jmjgnun name to argv|fl] 7 

if (prog^name •** NULL) 

return errlnvatNewAigParam; 

len = nong)stf]en(prog_name): 
if (leu — 0 || len >= kARG STRLEX) 
return -1; 

strepyf (*and) JargvfQ], ptrog_uiin3e): 
return noErr; 

} 

The following support functions set and get the arge and 
argv parameters and reset the CMDJ structure. 

Listing 17- GMD_i support functions (Args.c) 


SctNthAig 

copy string str to argvfnl (argvfnj <— str) 

n is _m based ^ count 

not allowed to set vector 0 

returns true - vector set. false - vector not set 

short SetKthArg(CHD_p_t cmd. char *str, short n) 

unsigned long len “ 0: 

if (and — NULL || str — NULL || n < I) 


return false; 
len = strlen(sxr): 

if den = 0 || ion >« ktmjmm) 

return false: 

strepyiemd >argv|iij, str); 
return true: 

I 


SefFinalArg 

the last argv must be a mill pointer (argvlargej <-- NULL) 
note: this trashes the argv pointer which b restored in ClearArglist 

void 5etFinaiArg[CMD__p t cmd, short rt) 

I 

if (n <- 0) 

return; 

cmd >argv[n] = NULL; 

J 


trfnArgVcaor 

return a pointer to the argv vector (char 'argvf]) 

ARGV t GetArgVector (CMD_p_t card) 

1 

return cmd >orgv; 

I 


SetArgNum 

set atgc to n (number of arguments + I) 

void SetArgNura(CHU_p_t and, short n) 

I 

and->argc - n; 

I 


GetArgNum 

short GetArgNumfCKD_p_t cmd) 

I 

return and >argc: 

I 


SeiArgFileName 

file name is special ease since it might be much longer than other args 
copy string filename to argv[D| (argv|n| <= Uloutoe) 
returns: true - filename copied; false not copied 

short SetArgFiieName(CMD__p t cad. char ’filename, short n) 

t 

unsigned long len = 0; 

if (cmd = NULL )| filename = NULL || 
n < l |1 ti kNUH_ARCS) 

return false; 

C if string is empty or too long, signal an error 7 

len - strlen(filename): 
if (len = 0 | | len >- kFNAMEJJ£N) 
return false; 
r copy the string 7 
$trcpy(and->fnaEtie T filename); 
t set the vector 7 
ctnd >argv[n] = cmd->fname: 

return true; 

1 


OearAigLisr 

reset CMDJ to initial state 

must call before setting new arge, argvfnj 

void ResetArgListfCHD p t and) 

long i; 

cmd->argc = 1; 

/* reset and dear all die: vectors > argvfflj */ 
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for (i - 1: i < kNUM_ARGS; i++) I 
cmd->argiist[i]fO] " 1 Vf)'; 
cad->argv [ij “ &(cmd >arg)lflt[i] fO])♦ 


/* clear file name */ 
cad ->fnaae[0] * *\0 *; 


I 


However, in Mac*MTDI2alx: l don't set CMD_t directly from 
the dialog. Instead, I maintain a separate “settings" structure 
(SETTINGS DLG _t) that mirrors the ^nite of the user interface, 
and set CMD_t from this structure- Note the correlation of the 
settings structure with the Settings dialog (Figure 10). 


Listing 18. The settings structure (SETTINGS DLG t) 

typedef short BOOL_t; 

typedof FourCharCode HACiC_u 
enum I SKTGJ1AGIC *= 'setg' I; 

^pragma options at : gn^lnacfiBk 

typedef struct sei l i ng__rit£_s I 
MAGIC.t magic 1: //'setg' 

short version; 

//Time Signature 
H0QL_t time; 

short Lime_val; 

BOOL_t ex L r ac t _r iraa: 

B00L„t de Caul l w t I me; 

// Key SlgiLiiurt; 
short key_val; 

ROOL.t defauit„key: 

// Channel 

short channel val; 

//Tempo 

BOOL_t qnotesja 1 n ; 

short qnotus_min_val; 

BOOL 1 extract_tiot*?_len; 

R00L t hars_output; 

long bars val; 

BOOL_i default tempo; 

//Anacrusis 

boa t fl_a na c ru: 
short anac:ru_vaU 

BODL^t ext r ac t_snacr u; 

BOOL t guess_anacru; 

BOOL t default_atiacru; 

MAGTC_t magic2; //^lg' 

I SETTINGS_DUS_t, ‘SETTINGS J}LC_p_t, * 1 SF.TTTNGS DLG_h; 
^pragma options al Ign^reset 


The “magic'' values at the start and end of the structure are 
for debugging and resource data integrity checking. The routine 
that sets the SETTINGSJDLGJ structure based on the Settings 
dialog is not listed 

The SFTTINGS_DLG_t structure is not dynamically 
alkx:ated Instead, l use a custom resource that matches 
SETTINGS_DLG_L The resource is loaded from a preference file 
and typecast to a settings handle (SETHNGS_DLG_h). I used 
Resorcerer to create a TMPL resource (Figure 11) that matches 
SETTINGS_DLGj, and then used the TMPL to create a setg 
resource with appropriate default actings (Figure 12) See die 
MacTeeh ank le on preference files (Sydow 1999) for more 
details on tills technique. 



Figure 1L Resorcerer TMPL forsetg resource 
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products you need, with the prices 
and service you deserve... guaranteed. 


Power Tools for Programmers! 



Whether you're a developer ol high end. complex applications, 
simpler utilities, sharewarwfreeware, an IS manager or an ISP 
who needs to distribute files quickly and easily, the new 
installer Maker b the complete installation solution for you. 
Utilizing the power of the new StufTU Engine. InstalterMaker 
creates in Mailers faster and smaller than ever, decreasing 
download time off servers and reducing the number of disks 
needed to distribute installers, These time and cost savings go 
straight to your bottom fine! 


VOODOO Server is a version control system lor software 
developers using Met reworks CodeWarrior under Mac OS 
VOODOO Server and The corresponding VOODOO clients [the 
included Code Warrior VCS plug-in and the VOODOO Admin 
application) are designed to offer reliable and robust version 
control features while minimizing the administrative overhead 
tbar usually accompanies version control If you’re a single 
programmer or managing a team of developers, version control 
can make or break your project. Do it right, with VOODOO 


One of the most flexible and powerful development 
environments on ihe Macintosh today! Easily create programs 
with the visual program editor, drop into the SASIC editor to 
define powerful logic with the worlds easiest programming 
language, or work directly wi[h the Macintosh toolbox. The 
only basic: compiler on the market that gives you 100% access 
to all of the power of the Macintosh toolbox? 


Installer Maker 6.5 I OK 


VOODOO Server 


Future BASIC 3 


CodeWarrior Pro 5 


CodeWarrior Professional 5 put everything you need for 
software development at your fingertips; project manage merit 
tools, text and resource editors, source and class browsers, 
compilers, linkers, assemblers, arid debugger.Release 5 offers 
such features as RAD for Java, taster compile limes, local and 
remote application debugging, IDE extensibility options and 
even tighter C/C + + compliance Additionally, you can create 
applications for Windows 95/98/NT and Mac 05 8,x and Mac 
OS X from either host platform, [available in versions hosted on 
Mac or Windows] 


Spotlight 




Spotlight is the first Macintosh "Automatic DebuggerIt can 
automatically locate run time errors in your code and display 
the offending source code line. Unlike simitar tools on other 
platforms Spotlight is easy to use. No source code changes 
are necessary for application debugging. Spotlight can 
automatically check for wild pointers, memory leaks, 
overwrites, underwrites, invalid dereferencing of handles, and 
even toolbox parameter validity checking ~ spotlight knows 
Macintosh verifying parameters to over 40G toolbox calls 


Resorcerer 2.2 


Resorcerar is the only supported general purpose resource editor 
for Macintosh Relied upon by thousands of Mac developers. 
Resorcerer features a wealth of powerful yet easy-to-use toots lor 
easier, faster, and safer editing of Macintosh data Bles and 
resources Whether you have to parse a pkturc, debug a data fork, 
design and try out Balloon Help, create a scripting dictionary, create 
anti aliased icons, design and edit a custom resource with 40,000 
fields in it. create c source code to run a dialog, or any ol hundreds 
of other resource-related tasks, Resorcerer^s magic will qturkfy save 
you time and money. 


and hundreds more! 
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Master the Web! 


WebSTAR Server Suite 4.2 


WebSTAR Server Suite is a complete set of powerful arid easy-to- 
use Internet servers for the Mac OS Effortlessly serve web 
pages, host email accounts, publish databases. and share files 
all with a single application on one Mac! WebSTAR Server Suite 
is perfect for Internet or Intranet serving, single or multiple sites, 
small I and large businesses it’s power and ease of-usc saves 
any organization time and money. 


Funnel Whb is the ultimate web analysis solution for 
professionals. Specifically designed for profiling web site usage 
•and monitoring customer usage patterns, Funnel Web is ideal lor 
examining server performance and online effectiveness. Tunnel 
!Web can analyze log Tie formats from any server, WfbSIAR, 
jwebfen, even Unix or (SI I hosted erwers Discover the most 
popular pages on yniir site, track server toads & optimize server 
performance profile visitors based on organization, domain 
•name, country, browser, etc. Funnel Web does ft all 1 



Monitor the bandwidth usage of up to five different machines on your 
network! Do you need to upgrade your Webserver? Mow hard Is your 
eMail server working? Are you getting all the bandwidth you're 
paying for? Not only can CyberGauge answer all these questions, 
new features allow CyberGauge to eMail or page your network device 
becomes unresponsive r passes a threshold of usage you define an 
essential first line of defense for early detection of denial or service 
attacks and necessity for warning you and tracking quality of ISPs 
that may have brown outs and shutdowns 


NEW! 


NetBarrier 


™ NetBarrier offers a Personal Firewall. Anti vandal pro Lee Lion, and 
Internet Filtering, Protect your machine from intrusions by Internet 
or AppleTalk, incorrect passwords and Individual art Inns are 
logged, you arc alerted to hostile actions, and intruders are easily 
Isolated internet f iltering allows you to be sure that passwords, 
credit card numbers, and other sensitive information can never be 
exported from your computer - the content itself is filtered before 
any transfer! (Rated 4 mice by Macworld Magazine! 



...and great hardware solutions! 


2 USB PCI Card 


Add two USB ports to your older Macintosh. Connect up to 
12/ devices to the Universal Serial Bus (USB) that is 
Apple's new standard for desktop connectivity. USB mouse 
devices, keyboards, joysticks, game controllers, printers, 
rscanners connect them ull to your current computer. 
Installs in minutes! 



Dr. Bott Moni Switch adb or usb 


Do you need 6 monitors and 4 keyboards for your 4 servers? 
With Dr, Bott Moni Switch you can connect a single keyboard 
and monitor to up to 4 machines at once! A simple flick ol a 
switch directs the video input and keyboard commands to the 
appropriate CPU! Available in USB and ADB models, with 2 
or 4 machine support, and bundles with USB PCI cards SO 
you can mix and match USB and ADB machines with the 
same Moni-Swifcth! Great for programmers to do back 
ground compiles, ideal for server rooms overcrowded with 
monitors and keyboards! 


- 
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Macsense USB Full Size Keyboard 

Macsense Internet Sharing Router 

Just plug this keyboard into your Mac and start typing! The 

UKB-600 keyboard from Macsense is designed to get yw ^ 1 

z#r. _ 

Looking to get your whole office online without shelling out 
^thousands of dollars? If so. the XRouter Internet Sharing / 

Hub offers the perfect solution this amazing Ethernet to- | 

Ethernet hub connects an entire network of up to 252 users 3 

to the Internet using only one ISP account and one Cable or 

DSL modem! ^ 

$199 

worries It features two forte translucent design, colored to 
l match your fovorite flavor of Macintosh. It olfers soft touch . 

: witfi positive tactile feedback and build built in USB port on Jk Ji 95 

either side of the keyboard. Includes a S' USB cable and is ®“W“¥a 
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if (and = NULL || set: h — MILD 
return false; 

// make the settings dialog the active port (ToolsPlus API) 

CurrentWf ndowiSeitingsWindow); 

// for MacMID12abc. first two arguments are ~*T and file name 
SetNthArg(and. *-f*. argc++); 

// use a file name placeholder for now 

SetArgFileNmne(and. “(no file name)", argc+ + ); 

// lime Signature 

If ((**set_h)•time = BUOL_QN) I 
// GetPopOpString is from the ToulsPlus API 

Get PopUpSt ting (PQF_Tinie h (**eet hhtimu val* mctnuEtr); 
GopyPascalStringToC(tnenuStr* arg); 

(void)SetNthArg[and, ”-ra H , srgH4) j 
(void)SetNthArg(and, erg, argc++): 


i 

else if ( ("setj), extract_time “ BOOL ON } 1 
(voidlSetNthArgCemd, “-xnT* argc++): 

I 


Figure 12. Default setg resource (Resorcerer) 


Note that BOOL resource data type is a short integer, 
and that FALSE is equal to 0 and TRUE is equal to 0x0100 (256) 

(Figure 13). 


=Q= BOOL from setg 1 28 "Conversion Settings * from MaeMDI2abcxsrc —- 

Extract Time from File 


Value: 

# False QTrue 


Figure /j, Setting the BOOL resource data tyfw in Resorcerer, 



I Cancel | 


To complete the cycle, here is how 1 set the arge and 
argv parameters (in the CMD_i structure) from 
SETTINGS^DLGj (Listing 10). Note how tlie layout of ihe 
function follows the layout of the Settings dialog (Figure 11) 
and SETONGSJJLGJ (Listing 18). 

Listing 19, Creating an argument list from the settings 
structure 


// Klv Signature 

if ( (“set h) .defaultJtey “ HOOL^OFP ) 

(void)SetNthArg(and♦ " k“. argc++); 

// convert popup mam index to integer from -6 6 
NunTaString( (* 4 set_h)*key_val - 7 t numStr ); 
CopyPascalSt rin gTo G(imuS1 1 > arg); 

(voidJSetNthArg{cud, arg, argc++j; 


// Channel 

If ( C*sci_hKchaiw«l_vai > 1) \ 

(void)SetNthArg(mod. “’C'\ argc++): 

// eon vert popup menu index to channel * 

NumToString( (**set h).channel_val l, numStr ); 
GopyPaseaiStringTbC(mimStr. atg); 

(void) SetNthArgTctnd , arg t u£gc++); 


//Tempo 

if ( ( # *set_h) .qnotes rain ** B00T,_0N ) ( 

(voidJSetNthArg(cmd, “ O - , argc++J; 

NumTuStringf (* # uet Jj)- qftQles_min_vBl, numStr ); 
CopyPascalStririgToCfnumStr. erg); 
tvoid)SetNthArg(end* arg. argc^H-): 

) else if { (**setjn) *extract_note_len BO0L_0N ) I 
(void)SetNthArg{emd. “-xl**. argc++): 

1 else if { (*“set h).bars, output — BQOLJJN ) I 
(void) SetNthArg (ami* " h", srgc++): 

NuraToString( (*‘3etji)-bars^val, numStr }; 

Copy Pa b ca 1S t. r 1 n gToC (nismS t r. a r g J: 
(vold)SelNlhArg(ami, atg. argc++): 


I 


//define B00L_TRUE 
fdefine B00L FALSE 
//define B00L ON 
//define B0()L_0FF 


0x0100 

0 

B0Ol,_TRUt: 

BO0L_FALSE 


Arg.dVmnSvitiiig>I% 

set the CMDjt struct un. from Lite SETTINGS structure 
returns true valid settings; false - invalid settings 


B00L_t ArgsFroniSett 1 ngsUIg (GUD_t end) 

I 

SEmNGS_nUUi setji = NULL; 

Strf 5 numStr " t0l» 

aenuStr - 101 : 
char arg[20]: 

long mm - -1: 

short index ” 0. 

arge * I: 

// GctScttingsDataff returns a handle lu Lhc global settings data 

so k _h - f SETTlNGS_DLG_h) GetSettingsUataH (): 


// Anacrusis 

if ( h)*bfiatB_anacru ** BOOL_ON } ( 

(void) SetNthArg, (cmd , " u'\ argc++); 

// convert popup index to anacrusis value 
NumToString( (‘.anacru_vai, numStr ); 

CupyPuscalStrIngToC (lUf&Str, a t g); 
(void)SetNthArg(cnirf, arg. argefi); 

J else if £ (**Est JO .extract__ariacru = B(X)L_UN ) f 
(void) SetNthArg( rind, " xa** ( argc++); 

| else if ( (■*sct_h).guesa_anacru = BO0L_ON } I 
(void)SetNthArg(ond, - ga", argc++); 


// imporuni; sei arp large| to N1T.L 

SetFinalAr^tcmd. arge): 

// how mam r paranieters were set 

£void)SetArgNum(ciad , (short) (arge)): 

CurrentWindowKesetO : #TwhPlusAPT 

return true: 

I 
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Exporting Symbols 

We have to export the GUI program symbols that the code 
resource will import from the resource initialization routine, just 
as we did for the code resource project, set the Export option 
(PPG PEF Target Setting panel) to Use ".exp" file (Figure 9). The 
next time your GUI program is built, the IDE will create an .exp' 
file with all the symbols in your program. Then, remove all the 
symbols except the ones you want to export anti add the \exp' 
file to the GUI project. 

Calling the Code Resource (CFM) 

To get the CL1 code to perform its task, we must load the 
code resource then call main with the argc and argv parameters. 
Firsi, we have to create Universal ProcPtrs for the CJJ routines. In 
tliis example, we wish to link with main and the initialization 
routine (MylnitCR, listing 8) in the code resource. 


Listing 20. Creating UniversaJProcPtrs for imported 
symbols 

emm I 

uppKainEntryProcIrita - kCStackBased 

RESULT SIZEfSIZEJBDEUizeof Unt) J J 

STACK ROUTINE PARAMETER(1, SIZE_CODE{sizeof(int))) 

STACK_ROirTNK_PARAMETER(2, SIZE C0DE( 


//if GENERATINGCFM 

typedef Univer&aiFrocPtr MainEntryFrocUFP; 

Adeline CallMainEntryProe(us«rRoutine, srge, argv)\ 

Gal Hintversa!Proc ((Tin I versaIProcPtr) (nserRoutine). \ 
uppMainEntryProctnFo, large}* (argv)) 

//else 

Typedef MainEntryProcFtr MainEntryProcUPP; 

tfdeflnc Cal 1KainRntryProc{unerRoutiae, argc. argv)\ 

{ 1 (userRoutine))t(argc)* (argv)) 

#endif 

emm I 

uppInitProdnfo - kCStackBased 

| RESULT SIZE(S3ZE_CQDE(sizeof{OSErr))) 

n 

#if GENERATINGCFM 

typedef UniveraalFrnePtr InilProclIFP; 

//define CallInitProc(userRoutine h param) \ 

Ca HUnivers&IProcC(Universal?rocFtr)(userRoutine)* 
ufipTnttProcIrafo. param ) 

//else 

typedef lnitProcPU InitProcUPP: 

//define CalllnitFroctuserRoutine. part«n)\ 

(*(userRoutine))((param)J 
ndif 

To call the code resource with the Code Fragment Manager, 
get a handle Uj the resource and use GetMemFragment to get a 
connection to the resource. Then call FindSymbol to link the 
desired symbols with the appropriate function pointers. Finally, 
call the actual routine with the UniversalProcRr listed above 
(Listing 20), Here is the basic outline. 
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* ha nd le - G et 1R eso u rce(); 

* GetMem Fragment (‘handle, &connlD,...); 

* Find$ymbol(connlD, ApmyCRMain’l...); 

* call the initialization routine or have it called automatically 

* MainEntryProcfmyCrMain, argc, argv); 

* call the termination routine (if any) or have it called 
automatically 


And here Ls the foil axle. 


Listing 21, Calling the Code Resource (CFM) 

// see listing 20 tor l'mversalFmcPtrs 
// function pointers for main and initialization routine 
typedef int UMainEntryFrncPtr){int, char * [ 1); 
typedef long (*InitFrocPtr)(void): 

MainEntryProcUPPmyCrMain * NULL: 

InitProrUPP mylnitCR = NULL: 


OllCodcRcsPPC 


caU PPC. code resource from PPC app 
accepts; argc, argv 

mums: error code, result (0 or 1} from code resource main 


int CallCodeResPPG( 

r 

int atge. char *argv[], 
QSErr 'err) 

I 

Str255 

er rName: 

Str63 

CRNaine; 

int 

result " 1: 

Cf ragSyinboiClass 

theSymClass ■ 0; 

CfragConnectionlD 

connXU = Or 

MainEntryFrocPir 

maitiAddr * NULL;// not used 

Handle 

handle * NULL; 


*err = 1j 


GOT BUGS? 

...and you're drowning in paper 
trying to keep track of them? 

You need BugLink! 

* BugLink is a client/server application allowing you 
to connect developers, testers, and support engineers 
anywhere in the world. 

* Intuitive user interface gives you the information you 
need at a glance. 

* Fully customizable database— add the fields you need 
to each project, 

* Custom TCP/IP protocol minimizes network 
traffic— ideal for dial-up connections. 

* Client applications can operate ’off-line*— allowing 
bug entry and modification even when not connected to 
the network! 

* Cross platform— set up mixed Macintosh and Windows 
environments in minutes with no additional software 
needed? 

* Try before you buy. Download and try risk free for 
30 days from http://www.pandawave.com/bl/ 

A 5 User License starts at $299; that's only $60 per person. 


The Pand aWave 

http://www.pandawave.com 
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// load i lit resource 

handle = GetlResource (kCodeRenType, kCodcReslD); 
it {handle = NULL) t 
*err = -1; 
return results 

\ 

HLock(handleJ; 

// establish a connection 

*err - GetKemFragtnent C ‘bandIn. QL. CRNaaie. 

kP r i va teCFra gCopy, koti&lD . 
(PtrM&restiitAddr. errName ); 

if (*err noErr) 1 

if link witli rht- main routine tfcscrlpitir 

'err - FindSymboKconnlD. ^prtiainRD 1 *, 

(Ptr *J&uyGrMain, 
itheSymClass): 

if (*err 1“ noErr J| myCr Ma I h = NULL) 
goto Fin; 

//link with the MyfnitCR mi nine descriptor 
*nrr = Find Symbol {connIB, **\pI(iitCRRD w , 

(Ptr *)&tnyInitCft, ith^SymClaos); 
if (*err 1= noErr || mylnitCR «** NULL) 
goto Fin; 

// manually iniluh/t ihe icsmircr, abort if err 

*err = (short)G#1 Unit ?roc f tny InitCR); 
if (*err J~ noErr) t 
go to Fin; 

1 

// cad the resume with .irjx. 

resuit - CallMainEntryProe (aiyCrMain, arge, argv); 
if dose the connection to the resource 
'err = GloseCormert innlkcorm i I)) ; 


Fin; 

HUniock(handle); 
KeleaseResoitrcet handle) ; 

return result; 

I 


Note that we arc linking witli tlx* routine descriptor symbols 
defined in our code resource, not die actual routine names 
(listing 7). Also note that arge and argv have already l>een 
extracted from ihe CMDj structure. 

Calling the Code Resource (68k without CFM) 

In MacMIDIZahe, I decided to rail the 68k resource from the 
68k code without the CFM, which allowed me to easily support 
older Macintoshes (Listing 22). Also review Listing 12, which 
demonstrated how the (>Hk code resource receives the routine 
address through arge and argv 


Listing 22. Calling the code resource (68k without CFM) 


CrilCodcRcstitik 

ini CallCadeResGBkfinf arge. char Xirgvfl, OKErr *nrr) 

Handle handle = NULL: 
int result = I; 

•err * 1; 

// toad the resource 

handle - GetlResourcefkCodeRenType, kCodeRestO&Bk); 
if (handle = NULL) 1 
“err - -J; 
return result: 

I 

IILockt handle): 

myCrMain = (MainEnt ryProrlIPP) (Uiandl . J; 
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You think the Internet is safe. 

Think again... 



NetBarrier. The first Internet 
security solution for Macintosh. 



All Mara connected to the Internet (dialup, 
DSL cable-modem) are exposed tit hackers. 
Whether you are a home user or a 
professional user, your data interests them. 
Tliill's why you need a security solution that 
only NetBarrier can provide. 

Personal Firewall 

NelBarrier protects and monitors all 
incoming and oingoing data- A customized 
mode allows you lo create your own 
defense rules, die re by offering die most 
secure level of protection. 


Antivandal 

NetBarrier blocks all attempts to break 
into your Mac, detects wrong passwords 
and logs vandal attacks for complete 
protection. Moreover, il has an alarm to 
inform you of every intrusion attempt. 

Internet filter 

NetBarrier analyzes data as i! leaves your 
computer and prevents unauthorized 
exporting of private information such as 
credit card numbers, passwords, sensitive 
da la and more... 
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U initialize ilie resource - pass ifte CopyliytesToBuffer address 

(void)aiyCrWalnC 1, (void *)GopyBytesToBuffer); 

// now cult the resource wiUi aigc, argv 
result = myCrHaintarge, argv) \ 

// call termination routine by setting urge to 0 

(void)tnyCrMainfO, NULL): 

HUnloek(handle); 

ReleaseResouree(handle): 

// no error relumed Irom 68k resource 
*err = noErr: 

return result: 

) 


Standard C Hie Operations 

The Standard C file operations (fopen, fwrite, fread) are well 
supported by the MSL C libraries. I lowever, the fopen operation 
takes the name of a file, not a FSSpec. and opens files in the 
current working directory unless a full pathname is specified for 
Lite file name. The Morcfiiles library provides two useful 
functions for setting and restoring the current working volume 
and directory: SetDefault and RestoreDefaull. These calls should 
bracket the Standard C file operations. 

In MacMIDI2abc t SetDefaull and RestoreDefaull bracket the 
CallCodeUesPPC and CaRCodeKes68k functions (Listing 23). 

Listing 23* Using SetDefault and RestoreDefault 

// fspec is the file ESSpcc 

// gd urge and urgv from CMJ>_i 

// c: library file routines are used inside the code resource 

err - SetDefault(spec->vRefNuni, spec-)parift. &oldVRefNum» 
&oldDirID): 
if { err = noErr } 
i 

#i£ powerc 

result 55 Call Cod eRnii P PC (a rgc ♦ argv, fcerr); 
j^else 

result = CallCodeResbSk(ar&c, argv, &err): 

#endif 

RestoreHefault (oldVKefNiim, oldDirlD) ; 

] 

Read the MoreFilesExtras.h file for more details about the 
SetDefault and RestoreDefaull routines. 

MoreFiles 

<http;//developer.applexom/samplecode/ 

Sample_Code/Files/MoreFiles.htm> 

Load Resource Once or Repeatedly? 

In Listings 21 and 22 the code resource is loaded and 
unloaded each lime the CL1 code is executed. Why not just load 
the resource, move the handle into high memory and lock it 
when the GUI program is initialized? 

Loading the code resource only once can crcaLe problems 
if the ('Ll code is not multiply reentrant. Static and global 
variables will retain their value between invocations, and may 


create unpredictable results. In MacMIDI2alx\ I found several 
errors in CU code execution that were eliminated when I 
reloaded the code resource each time. Keeping in mind the 
golden rule of porting, I decided reloading the resource was a 
better solution than rewriting the CU code. 

Step 4: Pitting It All Together 

To build your final application, add the code resource(s) to 
the GUI project. Instead of dealing with fat resources (which 
contain both PPC and 68k code), 1 used different IDs for the PPG 
and 68k code resources, and made sure the PPC code called the 
PPC resource, and that the 68k code called the 68k resource. 
Then he sure to register a unique creator type for your 
application, and give it a proper application icon (Figure 2). 

Debugging Tips 

During program development, I found several debug aids 
were invaluable. For the GUI program, make a “show 
arguments” utility that displays the arge and argv parameters in 
a dialog. It is helpful to ensure the user interface is setting the 
command line parameters correctly before connecting the GUI 
program with the code resource. 


Argument List ^Piplp 


Commune! line argument list 

Number of arguments: 8 
argvfO]: MacMIDI2abc 
argv[1]: -f 

argv[2): <no file name} 
argv|3): -m 
argv[4]: 3/4 
argviS]: “Q 
arcjv[6]: 75 
argv[7]: -xa 
arrjvfS): <NULL> 


Figure 14, Argument list dialog 

A second debugging utility I found invaluable was the 
cLecho program mentioned at the beginning of the article 
(Listing 3). Compiling this simple utility as a code resource and 
properly linking it with your GUI front end will pave the way for 
your more complex CLI port. 

One area that frequently trips up less experienced developers 
is debugging a code resource. Here are the steps to do it correctly. 

• create the code resource with the Enable Debugger menu Hem 
selected 

• build the application with the code resource 
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• double dick the .xSYM file for die code resource (not the 
application) to open the debugger 

• -set the breakpoints in the resource 

• launch the application, and die debugger will hall at the code 
resource breakpoints 


Summary 

WeVe just reviewed a lot of steps and scattered code snippets 
to demonstrate how to gel a CLI program ported to the Macintosh 
using code resources. To guide you on your own porting project, 
Tables 2 and 3 list the routines and files that 1 used for 
MacMlDT2abe which are described in this article* Listing 24 is a 
lisLing of all lite changes to main in MadV1TD12alx:. Finally, review 
the Cli Port Demo program available on the MacTech web site. 


Table 1* MacMIDI2abc GUI program file?* and routines 

(standard Mac GUT and event handling code) 

Atgs.c (structure and routines for handling arge and argv 
parameters) 

command structure (CMD_t) (Listing 15) 

NewArgList (Listing 16) 

SetNthArg* SetFinalArg. etc* (Listing 17} 

Settings.c (routines and typedefs for maintaining a 
"setLings" structure) 

Settings structure (Sh i I INGS_DLG_tJ (Listing Id) 
setg resource (Figure 11) 

ArgsFromSettingsDig (Listing 19} 

CodeReaourea,c (routines that interface with code resource) 

CallCodnResPPC (Listing 21) 

CalTCodeResftSk (Listing 22) 

CopyBytesToBuffer (stdio output in code resource ends tip here) 
(see the CLI Port Demo project for an example) 

SetDefault* RestoreDefault (Listing 23) 

MacMIDI2abc.mcp.exp (exported symbols) 


Table 2* MacMDID2abe code resource files and routines 

midi2abc.c, midifile.c (original midilabc CLI code) 
main (Listing Vi) 
console.stubs*o (local copy) 

WriteCharsToConeole (Listing 6) 

CR,glue,C (Initialization and termination routines) 

MylnitCK (Listing 8) 

MyCR68k (Listing 13) 

MyTertninateCR (Listing 12) 

exit,glue,c (override MSI, exit routine) 
exit (Listing It) 

_GeLHieinWiLlifree,c (local copy) 

_sys_allot (Listing 9) 

FreeAllMallocHemory 

MIDI2abc CR*mcp.exp (exported symbols) 


Listing 24. Changes to main routine in fnidiiabc.c 

#inelude <setjnip,h> 

^include <A4Stuff.h> 

jmp_buf myjuapbuf: 


lot main (lot urge* char *argv[J) 


main 


i 

// krai variables here 

volatile int val; 

KnterCodeResource(); 
if (arge <* 0) I 

InitCR68k{arge, (void *)argv); 
ExitCodeResourceO; 
return£Q); 


if (val = setjnip(myjumpbuf)) I 
ExitCodeResourceO ; 
return (val - 1); 

} 

// routines to handle argp,aij>v and process midi files here 

Exi tCodoResource (); 
exit(0); 
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By Aaron Montgomery 


Using Flex and Bison 


Scanners, Parsers and 
Abstract Syntax Trees, 
oh my1 


What Are Flex and Btson 

(And, Why Do I Need Them) 

Flex and bison are code-generating 
tools designed to aid in compiler 
development. In particular, ilex (short 
lor fast lexical analyzer) will take a 
sequence of characters and break them 
apart into tokens (words), it could be 
used lo write code breaking this article 
into a sequence of words and 
punctuation. Bison (whose name comes 
from V ACC—Yet Another Compiler 
Compiler) will group the words into 
sentences, the sentences into paragraphs 
and the paragraphs into sections. But 
wait, you protest, I don'i write 
compilers. Thai's okay, there are still a 
number of reasons to learn a little about 
flex and bison. First, you may find that 
writing (or even understanding the code 
behind) a simple compiler may make 
the syntax errors coming from other 
compilers more understandable. There 
are also situations where you might 
want to be able to analyze a sequence of 
tokens even if the final output is not 
compiled code, For example, if you arc 
transferring data over the Internet in the 
form of strings, you can use flex and 


bison Lo create a parser to decode the information. 

My own personal experience with flex and bison began 
in a course in compiler design at the University of 
Wisconsin-Madison and 1 am currently working on 
re i in piemen Ling an interpreter for the language isetl in ANSI 
C++. *Phis recent work has required that I brush up on my 
skills with Hex and bison (in the Metrowerks' CodeWarrior 
environment) and doing a small project with a toy language 
similar to isetl seemed like a good first step. 

This article will presenl a small simple language called 
Miniset and then present (he steps I followed to develop a 
parser for the language. It is highly unlikely that you have 
ever used (or even heard of) Miniset, largely because 1 
made it up last month in order to practice with flex and 
bison before working on isetl. The final result will be an 
application which simply echoes out the source you type in 
(although it will make it conform to my stylistic 
conventions). This echo application is probably a good first 
step in any parser's development since it allows you to 
confirm that your parser is correctly interpreting the source. 
The next step would be to write the code to implement the 
Minisct source, but lhaL would be another article. 

This article will assume some understanding of C++ 
allhough bison and flex can be used even if you intend to 
do all your programming in C, You are also expected to 
have a basic understanding of the CodeWarrior IDE (in 
particular, how to adjust project .settings in preference 
panels). While I will spend some lime on the peculiarities 
of using flex and bison in the CodeWarrior environment, 
much of the article remains valid in other environments 
(or even other operating systems), A basic understanding 
of Minisct may come in handy in places and there is a 
short overview of the language included with the project 
file. This article does not assume that you have any 
previous experience wkh cither flex or bison. After 


Aaron Montgomery wastes (excuse me. spends) a lot of time thinking about things like ibis when he really ought to be 
preparing his calculus lecture notes. Currently, he is finishing up a 3 year Visiting Assistant Professorship at Purdue University 
North Central and moving on to an Assistant Professorship at Central Washington University starting in Fall of 2000. He hopes 
to use the money he gets from this article to buy a bunch of Rokenbok remote control vehicles and building sets. 
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reading the article, you will hopefully have enough 
understanding of Hex and bison to determine if they suit 
your needs. In addition, you will have seen some of the 
issues that can arise as you try to build a parser or a 
scanner with these tools. This article does not intend to 
provide a complete introduction to these tools. If you 
decide that you are going to use flex or bison, then 1 
would strongly encourage you to obtain a copy of the 
book lex & yacc as well as download the bison and Ilex 
documentation (references available at end of article). 

IIow Fllx xnd Bison Work 

Before discussing this particular project, an overview 
of how flex and bison operate is probably appropriate. I 
will call the inpuL file for Hex a "scanner spec i flea lion” 
and it is conventional for it to have an I suffix, I will call 
the input file for bison a "parser specification" and it is 
conventional for it to have a y suffix. When you tell flex 
or bison to process its input file, ii will produce a file 
containing C/C++ source code, I will call these files 
source files in order to distinguish them from the 
specification files. Your own code will probably call the 
function yyparseQ created by bison from your parser 
specification. This function will in turn call yylexQ created 
by flex from your scanner specification. You can use 
yylexQ independent of yyparseQ and you can supply your 
own yylex() to be used with a bison generated yyparseQ. 

When you trail yyparseQ from your code, the parser will 
repeatedly call yylexQ to obtain tokens (words and 
punctuation) from the input stream. With each new token, 
the parser will decide whether to push the token onto its 
internal stack or to reduce a sequence of tokens on the 
stack to create a new language pan lo push onto the stack. 
These new parts of the language are referred to as “non¬ 
terminals". One of the non-terminals is the "start-state”. 
When this non-terminal is matched, yyparseQ will return. 
This is probably best explained with the following example. 

Assume that Lhe language knows that a noun phrase 
consists of an article ("the” or “a") followed by a noun. 
That a sentence consists of a noun-phrase, a verb, a noun- 
phrase and a period. Furthermore, assume that the parser 
is attempting to match a sentence. The non-terminals here 
are the noun-phrase and the sentence, the tokens are 
articles, nouns, verbs and periods. The start-state is a 
complete sentence. If the input stream consists of "The 
man ale a worm." then a call to yyparseQ will result in the 
sequence of events depicted in Figure 1. 
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* The parser will obtain the first token from the scanner — 
obtaining “The", an article. The parser will push the "The" 
on the slack (Figure 1-a). 

* The parser will obtain another token from the scanner — 
obtaining "man”, a main. Since there is an article on the 
stack, the parser will pop the article off the stack anti 
replace it with a noun-phrase "The man" (Figure 1-b). 

* The parser will obtain another token from the scanner — 
obtaining "ate", a verb. There is no rule reducing “noun- 
phrase verb" so it pushes “ate” on the stack (Figure I-c'L 

* The parser will obtain another token from the scanner — 
obtaining “a*, an article. There is no Rile reducing “noun 
phrase verb article" and so it pushes the “a" on the stack 

(Figure 1-d), 

* The parser will obtain another token from the scanner — 
obtaining “worm”, a noun. The parser can now reduce 
the “article noun* on the top of the stack to a noun phrase 
and places the noun-phrase on the stack (Figure 1-eX 

* The parser will obtain another token from the scanner — 
obtaining a period. The parser can now reduce the 
“noun-phrase verb noun-phrase period" to a sentence and 
places this on the stack (Figure 1-f). 

Tlie parser has now matched a sentence and returns. 
When the parser returns, its internal stack vanishes and so 
you are responsible for finding some method of returning the 
information you need from that stack. The most common 
met hex! (the one used in this article) is to use a global pointer 
to the needed information. You can save this information 
because will execute a block of C/C++ code dial you provide 


each time bison matches a pattern. Frequently, these blocks 
of C code will be used to produce something called an 
“abstract syntax tree" or “A ST' for short. Abstract syntax trees 
are data structures designed to mirror the syntactic structure 
of the pattern being parsed. For example, the abstract syntax 
tree from the sentence above might look like the one in 
Figure 2 (note, we don't need to have a period included in 
the tree since it occurs for all senrences). 


Sentence 

Noun-phrase Verb Nnun-phrasc 

/A “ /\ 

Article Noun Article Noun 

The mao a worm 

Figure 2 An abstract syntax tree , 

Bison facilitates this construction by assigning to each 
token or non terminal a value and the block of C/C++ code 
for a rule reduction can use the values of the tokens and 
non-terminals in the pattern to .set the value of the non- 
te rrn inal be i n g rec I u ced ■ Y( > u w ill be irn 1 1 x 1 u vex 1 to the deta i 1 s 
of this in the description of Parser 3 below. 

Installing Flux & Bison for CodfWarrior 

The flex and bison plug-ins do not come packaged 
with CodeWarrior, so the first thing you will need Lo do is 
get them, (an URL is provided at the end of this article). 
After decompressing the folders, you should place the flex 
and bison folders into the CodeWarrior PJugins folder of 
CodeWarrior, You now need to make sure that the file- 
mappings are correct. In the project settings, you should 
make sure flex is associated with the file suffix I and the 
precompile flag is set and that bison is associated with the 
file suffix y and the precompile flag is set. If you don't set 
the precompile Hug, CodeWarrior will complain of an error 
(from the old source file) and then show you the source 
where the error no longer exists. 

If you intend to only use them to generate PPG code, 
then you are set. If you plan to generate code for a 68K 
processor, you will need to change the purser skeleton file 
called bison.simple which is in the Bison plug-in folder. This 
change is needed to support a limitation in Code Warrior's 
implementation of the alloca() function in the 68K 
environment, I reported this to Metrowerks and received a 
work-around. You should replace the file in the Bison plug¬ 
in folder with the file included with the project. The alloca{) 
limitation only affects 68k development and there is a work¬ 
around so I suspect (even hope to be honest) that it sits low 
on Metrowerks 1 priority list. 
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Another problem is that it is easy to edit the source file 
(for example after a compile error or while debugging) and 
forget to change the specification file. If you do this, flex and 
bison will overwrite your changes the next time you run 
them. Tills can be particularly frustrating when you 
infrequently change the specification files. You can fix the 
error in the source file, leave the files untouched for a month, 
then rebuild the project and (mysteriously) a bug which you 
thought you had fixed a month ago will reappear 

Tin: Project 

The project builds a parser for a language called 
Miniset, Mini set is a small language handling the 
implementation of sets of positive integers. It is 
complicated enough to present some common issues in 
writing a parser and a scanner, but simple enough that the 
flex and bison specification files are manageable. Since 
Miniset is intended to be an interpreted language, the 
parser will assume that it should read each statement you 
type into the text window, execute the statement (in our 
ease, just echo it back to the screen) and then wait for 
you to type in the next statement, I have tried to 
document the less obvious language constructs in the 
parser specification files. If you are interested in learning 
more about the language, you should read the short 
introduction to Miniset included with the project and 
work with the output application of the Parser 8 target. 
This output application wall read what you have typed 
and echo it out to the screen. If you end the session with 
the quit command, ii will then echo your code out to a 
file called miniset one. then read it back in (reparsing it) 
and then echo it out to a file called miniset two. This file 
Creation is done as a chec k on the internal consistency of 
the parser (both files should be identical). 

The project has eight targets (aptly named Parser 1, 
Parser 2, ... Parser 8). They each present a different stage 
in the process of building the final application (Parser 8), 
This article will attempt to lead you through the sequence 
I used w hen building the parser and you can follow along 
with the files. Due to length issues, it would be 
inappropriate to document every difference between the 
project files, but you can use a diff tool (like 
CodeWarrior’s Compare Files...) to quickly identify the 
changes between the stages of the project. Here is a 
general overview of the eight targets: 

•Parser h initial parser (bison) specification, lots of warnings 
generated by bison 

• Parser 2: rewrote portions of the parser specification to 
eliminate the warnings 

• Parser 3 added C++ axle, resulting source file compiles 

• Parser 4: initial scanner (flex) specification, there are 


some problems while scanning 

* Parser 5: fixed the scanning problems, some bugs in the 
parser specification are now visible 

• Parser 6: fixed the bugs discovered in Parser 5 

• Purser 7: added better error handling 

* Parser 8: repackaged the scanner and parser as a C++ class 

Parser 1 

Writing the parser specification 

The primary purpose of Parser 1 is to introduce you to the 
notation used by bison. If you already have some familiarity with 
such specifications, you might lx: able to identify the mistakes in 
the file as you read through it. Hopefully, by Parser 6 we will 
have resolved all such problems. The project consists of a single 
file (parserl.y) which is the first attempt to produce a bison input 
file for MinLset. 

bison specification files have three sections (separated by 
lines containing %%. The first section of a bison file (from the 
start of the file to the first %%) Is called the Definitions Section. 

parser I y (Definitions Section) 

//punctuation 

tttoken T_COMMA, T_SFMTCOLON 
tttoken T_OPM_PAREN, T^CLOSF PARF.N 
%token T_ERD 
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Ktoknn T_HULT1PLV 
%start nt_program 
%% 


Tlii.s section provides information that is placed at the 
top of the resulting source file or which is needed by 
bison to create the parser. Lines beginning with 
whitespace will be copied verbatim into the resulting 
source file near the lop, but you should restrict yourself 
to comments on such lines because there is no guarantee 
about their exact position in the resulting source file. 
Similarly, lines contained between a %{ and a %} are also 
copied verbatim into the souree file. 

The other lines beginning with a % are information that 
bison needs to construct the parser. Currently there are two types 
in die file: %token lines and the %start line. The lines beginning 
with %token list the tokens that the scanner returns to the parser. 
It is conventional to name these with all upjxTeasc Idlers (1 add 
the T prefix as well). Assuming die Generate Header option is 
selected in the bison preference panel, bison will generate a 
[leader file which ^defines each token to lx: a unique integer. The 
scanner function, yylexO, should use these tokens as return 
values. The ordering is unimportant for now (however, it is set 
up to make the transition to Parser 2 easier). 

The %start line tells the purser that it is attempting to 
parse something called an nt program Non-terminals arc 
conventionally written in lower case (I add the nt_ prefix as 
well). The specification defines the non-terminals in the next 
section: the Rules Section. 

The section Ixtween the first %% and the second %% is 
called the Rules Section, Thus section clescribes the non¬ 
terminals in the grammar (those things which are built from 
tokens and other non-terminals). The Rules Section in 
parserl.y is long and I have omitted a number of rules. The 
lints displayed Ixlow are representative of what you find in 
a rules section and they contain all the code of interest 
(including the bugs). 


parserl.y (Hairs Section) 

nt_program 

nt statement list ni_qull_statement 

ti l _qui t_s t atemen t 
TjQUIT T_SEMICOLON 

nt BtatRraent_lisL 

r empty 7 

l 

nt_5tatemerit 

lit star^ment_llGi nL statement 

//code omitted 
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nt_mimbt?r 


T_KUMBKK_L1TEKAL 
' T NUMBER.IDENTIFIER 
tiL.inrmber T MULTIPLY nt_number 
T_ADD nt number 

T OPEN„PAKEN nt_number T.CLOSE PAREN 

I 

T_NIIHBER IDENTIFIER T_OFEN_HKACE 

nr fixprfission list T_CLOSEMBRACE 

//code omitted 

A rule describes to the parser when ii can do a 
reduction, t he result of the reduction fa non-terminal) is 
given first followed by a colon (:)* then there are a 
sequence of patterns separated by vertical bars (I) and 
finally a semicolon (;). After each pattern, there is an 
optional block of erode. Some of the blocks in parserl.y 
contain comments about the Miniset grammar. 

parser I .y (Ru k Seel ion) 

nt_prograro 

rit_is tat omen i I \ nr nt quit statement 

nt quit„statement 
T.QIJTT T SEMICOLON 

nt^tuLenivn t_t hi l 

t empty 7 

I 

nt statement 

ni_alainmrnt list nt statement 

//code omitted 

nrenumber 

T NUHBEJU.ITERAL 
^ T_NIJMBER IDENTIFIER 
nt_numbor T_M1ILTTPLY nt number 
nt_number T_Ai)D nt_numbor 
^ T OPEN PARED nt^number T_CLOStt_PAREN 

i 

T_NUMBRR_ IDENTIFIER T OPEN_BRACE 

nL_express Ion. lint T CLOSE_BRACE 

//code omitted 

%% 

It is conventional to have die start state as die First rule 
in the list and write the specification from the top down. The 
first rule given above tells the parser that an nt,program is an 
nt_statement_list followed by an nl_quit_statement, 

The second Rile describes an nt_quit_statement as the 
token T QUIT followed by the token TJdEMJCGLON. In oilier 
words, a quit statement looks like: 

quit: 
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The third rule tells die parser that a restatement list can 
either be empty (the first possibility). Empty reductions are 
typically listed first and indicated by t empty 7, Or a list may 
contain a single restatement (the second possibility). Or a list 
can he obtained recursively as an ntstatementjist followed by 
an nt_£tatement. Notice that the recursion could have been 
presented as nt_statement ntstatementjist. Although Ixah 
presentations are equivalent, the first form is preferred since the 
second would require all the nt_ statements to be pushed onto 
die stack before a reduction could occur The first form allows 
the nt_statement list to be placed on the top of the stack first 
and ihen allows it “gobble up* each following restatement as 
it apjxrars in the input stream. 

The third (and final) section occurs after the second %% 
and consists of C/C++ code dial bison will place in the 
resulting source file. This section typically includes any code 
for additional func tions needed. Currently we don’t require 
any and so this section is empty. 

Processing the parser specification 

Now f issue the Make command. If this is the first time 
you make this project, you should get a message that you 
need to add a file to the project and then a message 
stating that the file you should add cannot be found* Just 
issue the Make command a second rime and everything 
will be all right. You will get similar messages on the later 
targets as well. Occasionally, 1 have also received an 
“unknown error’ 1 message which can usually be solved by 
trashing any previously created parser files (in this case, 
parserl .tab,h, parsed dab.c and parser 1 .output). 

More importantly, you should get a warning message 
indicating that there are a number of conflicts (1 7 0 to be 
exact). A shift/reduce conflict occurs when the parser 
cannot decide if ii should shift a token onto the stack or 
reduce to a non-terminal. A reduce/reduce conflict occurs 
when the parser cannot decide which reduction rule to 
use to reduce the stack. You should attempt to remove all 
of these errors from your parser specification, although 
this may be difficult (or even impossible), In any case, 
you should identify each of them and determine that the 
parser is doing the correct action in each case. 

Now that we know we have errors, we will adjust 
some settings to get dearer messages. In the Bison 
preference panel, you should check the Verbose 
checkbox. This will result in more informative warning 
messages (containing information about the “states" in 
which the bugs occur). You will now want to Touch the 
specification file and issue the Make command again. 
During this build, you will receive more explicit warnings 
about the shift/reduce conflicts. The warning messages 
grow because each new warning message is appended 
Onto the previous warning. This means that you will need 
to use the horizontal scrollbar to see all of the messages. 
You should write down all the states that are listed as 
having conflicts (or if you are lazy like 1 am, just write 


down a few and go work with them first). 

Checking the Verbose checkbox also causes ihe file 
parserl,output to be created in the same file as parserl .y, 
The parsed ,output file contains a description of the parser 
in terms of a finite-state-machine. You don’t need to know 
much about the theory behind this, but the basic principle 
is that as each token is processed, rhe parser moves from 
one state to another (these are the states referred to in the 
warning messages). The parserl .output file describes these 
movements but it can be intimidating at first. In the next 
section w f e walk through some of the entries ro determine 
the problems with Parser I, 

Parser 2 

Adjusting the parser specification 

Open the file parserl.output (ids pretty scary, you 
might want to close the file, take a deep breath and then 
open it again). At the top of the file are all of the 
reduction rules that are used as well as information about 
where each token is used in rhe file. Following this 
information are the definitions of each state. You should 
look for rhe definitions of the states with conflicts. 
Because each state definition begins with a line 
containing the word “state" followed by the state number, 
you can use the regular expression facility of the Find 
dialog to find a state’s definition quickly. For example, to 
find the definition of state 47, search for A state 47 with 
Regexp checked in the Find dialog. The symbol A indicates 
that you are looking for a match at the beginning of a 
line. Using Lhe list you made :ii the end of the previous 
section, you should look at what is happening in the 
states with conflicts. Your exact state numbers may vary 
from those presented in this article, but I suspect they do 
not. We start with the problem in state 0, 

parser (.output estate 0) 

stale 0 

T OPEN PAREN sbI ft * and gp to state 1 

T IF shift, and go to state 2 

T_FQR shift, and go to state 3 

//code omitted 

T_OPEN_PAREN freduce using rule 3 
(nt_statement _1iat)1 

T IF [reduce* using rule 3 fnt_statement list)l 

T_F0R [reduce using rule 3 Cut.statement list)) 

//code omitted 

When presented with an TJDPEN_PAREIN, the parser 
has the choice of shifting the token and going to a new 
stale (line 3 in the listing above) or reducing the empty 
stack using rule 3 (line 9 in the rule above). You should 
inspect the states to which the parser moves after it does 
the shift. You can use regular expressions to find state 1 
(or just scroll down the screen a little). 
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parscrl.ouiput (Matt I> 

ritAre U 

nr-> T OPEN PAREN . nt^set T_CLOSE_PAREN 
lUjumb^r > T OPEN PAREN * nt^number TjCLOSE_P AREN 
nt„boQlc?an -) T_OPKN PAREN « nt_booJLean T_CbOSE_PAKEN 

The non-terminal to the left of ihe arrow (->) is the pattern 
the parser Ls attempting to match. The period (♦) in the listing 
indicates the currentlocation of the parser in this attempt, items 
after the arrow and to the left of the pericxl are cm the stack and 
items to the right are tilings that ihe parser would expect to see 
in the input stream. In this ease, the parser is trying to match an 
nt_set f an nt_number or an nt_boolean It will have an 
T OPEN PAREN on the stack and is expecting either an nt set. 
nt„number or nt^boolean. The parser is attempting to match an 
expression and in Miniset. an expression followed by a 
semicolon is a valid statement {causing the value of the 
expression to lx* printed). From these clues, you can infer that 
the parser is attempting to build an restatement on the stack. 

The alternative to this shift and move is to use rule 3 is 
to reduce the stack. At the top of the file parserl .output and 
you wall find a list or rules. Rule 3 is the following: 

parser 1 .1 nit pur (rule 3) 

rule 3 nt_nt atetm^nt list ) P empty 7 

The reduction would use the empty stack as the start of 
an nt_statementjist. Since we wanL to allow an empty 
statement list, we will want to allow the parser to reduce with 
rule 3 and then allow the nt^statementjist on the top of the 
stack to append the first nt_statement. Tills changes the rule 
for nt„statementjist to the following: 

parse r2.y 

in_y L a lemont_1 1st 

I r empty 7 

nt etatetnent_list rrt__statemeut 

This problem isn't limited to nt_stalement_lists anti 1 have 
also adjusted the rules for nt _parameter_list. nt_number list and 
nt_expressionJist in parser2.y. 

If you look at all the states with conflicts that are not caused 
by lists, it becomes dear that all of them involve operators. An 
example of this type of conflict can lx seen in state 90, 

parser! output (stale 90) 

rit_munber -> nt_uumbet . TUMULT!PLY nt_number (rule 68) 
nt number -> nt_number , T_AUD nt_m,vmbor (rule 69) 
nt number -> nt number T_ABD nt_mnnber . (rule 69) 

TjWIIJ shift* and go to state 58 
T„MULTI PLY shift, and go to state 59 


T_MULTTFLY[reduce uning rule 69 (nt_nmnber)J 
$<lefaul l reduce using, rule 69 (nt_nuraber) 

Conflicts occur when a reduction is possible which 
means the trouble is with the third rule (line 5) of this state, 
the stack contains an expression like “2 + 3 n and a 
reduction is possible. The conflict arises if either a "+* or a 
is seen next, in this case, it would be possible to shift 
the new token onto the stack and reduce the expression 
from right to left. This would be the correct behavior if the 
new token were a since the multiplication should be 
performed before addition. On the other hand, if the next 
token were a “+” then the first addition on the stack should 
be reduced (since addition is done from left to right). 

ihe appropriate behavior dejxmds on the precedence of 
the operators involved. One solution to this problem is to 
introduce some new non-terminals for factors and terms and 
then rewrite the operator rules to reflect when shifts and 
reduces should be [>erformed. Fortunately, this problem is 
common enough (and the introduction of new non terminals 
confusing enough) that bison provides a simpler solution. 

In addition to die %token declarations we used in 
parserl .y, you can declare operator tokens using %lefF %right 
or %nonassoc These three identifiers determine whether the 
operators associate to the left (meaning a + b + c * (a + b) + 
c), to tlte right (meaning a + b + C = (a + b) + c), or if it is an 
error to fail to provide exact grouping instructions. In addition 
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to indicating the associativity of ihe operator, the %ieft, %right 
nr %nonassoc provide the operators with a precedence level 
based on their order of definition. The sooner the operator is 
defined, the lower its precedence. We therefore change the 
operator token definitions in parser2.y to the following; 

parser 2,y 

//operations 
%uonassoc T_GHTS 
ftnonassoc T.EQUAL, T T.ESSTHAN 
%nona&soe T UNION, T_T NTERSKCT 
ttnonadaoc T NOT, T_ANI.). T_OK 
Waft T_ADfJ 
%1ofL TUMULT 1 FLY 

The T GETS operator (assignment) is given the lowest 
precedence so that it will always be executed last and 
T_EGUAL and T_LESSTHAN given second lowest precedence. 
Operators on one type of variable won't conflict with 
operators for a different type of variable and so the placement 
of the set and btxjlean operators is unimportant in relation to 
the placement of the number operators. For both of the set 
and bixjlean operators, we declare them rton-assodative 
(meaning that a Minisct programmer must always provide 
explicit grouping). Finally, the addition and multiplication 
operators are declared as left associative with addition having 
a lower precedence level than multiplication. 


Processing the parser specification 

When you issue the Make command, (with the Verbose 
option), there ;ire 20 warnings, one for each place a precedence 
rule is used. You should check the parser2. output file to confinn 
that die correct action is being taken in each case. At the top of 
parserZoutput is a listing of where precedence rules were used. 

p:irser2.<>utput (lop of tile) 

Conflict in state 49 between rule 72 and token T3QUAL 
resolved as reduce. 

Conflict in state 49 between rule 72 trnd token T_AND 
resolved as an error. 

Conflict In state 49 between rule 12 and token T_GR 
resolved as an error. 

//code omitted 

state 49 

nt boolean -) nt_boolean * T_ANL3 nt_boolean (rule 70) 
nr boolean > nL_buolean * T_0R nt_boolean (rule 71) 
nt_boo]eaii -> T_N0T nt_boolean . (rule 72) 
nljjoolean -> nt_boolean . T EQUAL nt boolean (rule 75) 

T_AND error (nonassociativ<0 
T_0R error (nonasfuiciflt i ve) 

Sdefault reduce using rule 72 (fit .boolean) 


The conflicts will occur in the third rule reduction 
(line 5 of staLe 49) where a reduction is possible. If an 
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equa] .sign is seen, a reduction is made (since the equality 
operator has second lowest precedence). If either of the 
other boolean operators are seen, the parser will push the 
error non-terminal onto the stack This is a special non¬ 
terminal (you don't define it yourself) which indicates that 
the input stream contains a sequence of tokens which 
cannot occur in the language. This is the correct action 
here because the boolean operators require explicit 
grouping. To Parser 7, some use of this non-terminal is 
made to allow for better error handling. 

Now that the only conflicts have been explicitly handled 
by the parser specification, issuing the Make command 
without the Verbose option will result in no messages. 


Parser 3 

Adding the C/C++ code 

We are now ready to start adding the C/C++ code. Up 
until now we have been ignoring the files created by the 
bison preprocessor. The output files will have the same 
root name, but will have the file suffix y replaced by the 
file suffix tab.c. The goal of Parser 3 is to write a parser 
specification (parser3.y) from which bison will create a 
source file (named parsers.tab.c) which will compile. We 
need to add the C/C++ code to be executed as rules are 
reduced to parser3.y. In addition, we will need Lhe header 
files for any classes we use (although we won't actually 
need the source files for these classes until Parser 4 where 
we try to link the project). 

The definition section undergoes a fairly significant change. 

parstr3.y (Ddnition Section) 


XI 

^include “parser, h" 

^include Calloea*h> 
namespace [ 

inlineint yylex(void) I return 0 ; I 


1 

XI 

Xunion \ 

CStatementList* 

CS t a l ernen u Mod e * 
CElselfList * 
CElseliNode* 
CElseNode* 

//code omitted 

I 

//code omitted 

%type<iiiseIfLiet> 

%type<ElseIf> 

%type<Else> 

%t y pe<Id entiflerLAs 
%type<Trient1fler> 
%typp<MsimberList> 
%Lypt?<Niiinber> 
Xiype<13ooiean> 

// code omitted 

%token<Identifier> 
// code omitted 


StarementList; 
Statement; 
EIselfList; 
Elself; 

Else; 


nt elnelf_l1st 
nt_e 1 set f 
nt_el.se 

t> nt_p&rameTer_Iiet 
nt_parameter 
nt_number_iist 
nt number 
nt boolean 


T_SET_IDENTIFIER 


The code between the %{ and the %} is C/C++ code 
which will be placed at the top of the source file. We 
need to include the header parser.h (which contains our 
class headers) as well as the header alloca.h (which 
contains the memory routine aHoca{) used by the parser). 
We also define a stub function yylex() (in Parser I, we will 
have flex generate this function). 

Recall that the values of the tokens and non-terminals 
are available from within the code-block associated with 
a reduction to a non-terminal. These values are stored in 
a union data “type and the %union declaration determines 
the members (and types) of that union. In our case, these 
are all pointers to C++ objects. I will talk about these 
classes (very briefly) in the discussion of Parser 4, For now 
it suffices to say that they are all subclasses of an abstract 
class ('ailed CNode. 

Next comes a sequence of %fype declarations. 
Frequently in the rule reductions for a non’terminal, you will 
assign a value to the non-terminal (so that it can be used in 
later reductions). These %type declarations describe to 
which member of the union the parser will assign the value. 
You will only need a %type declaration for those parts of the 
grammar whose values you use in same rule reduction, if a 
token has a value associated with it, you identify its 
associated union member in the %token declaration (with 
the same syntax as the %type declarations). 

Because all of the types are subclasses of the class 
CNode, one might be tempted to use polymorphism to 
reduce the union to just a CNode*. However, doing this 
would require the class constructors to accept a generic 
CNode* and then downcast it in the constructor. Taking 
the time to correctly describe the union (as well as specify 
the %type declarations below) will allow more rigorous 
static type checking. 

Tlie rules section also sees substantial changes. As 
described in the general introduction to Ilex and bison, we 
attempt to generate an abstract syntax tree reflecting the 
structure of the input stream. My general strategy is to build 
a C++ class hierarchy matching the grammatical hierarchy. 
This means that if there is a nan-terminal called nt_statement, 
then I create a class called CStatementNode, similarly, the 
non-terminal nt assign statement corresponds to a subclass 
of CStatementNode (called CAssignNode), Almost all code 
blocks are then simply passing the values from the left side 
of the reduction to the constructor of the class corresponding 
to the non-terminal being reduced. 

The value of the non-terminal being reduced can be 
accessed as the “variable" $$ The values of the non-terminals 
and tokens on the right are accessed through the “variables'’ 
$1, $2, $3, and so forth. All non-terminals and tokens on the 
right are assigned a $ variable (even those which do not have 
an associated union memlxjr). However, you should only use 
those non terminals and tokens for which you have provided 
a type (and bison will complain if you try to do otherwise). 
If no rule is given, the default rule is 

$S - *i; 
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Tlii* rule assigns the value of the new non-terminal to the 
value of the first token on the right. [ tend to write this 
rule where I will use the value of the result and allow 
bison to provide it in cases where 1 do not use the value 
of the result (e,g,, in the reduction for nt_endjf in the 
code below). The following code is a sample of what the 
new code blocks look like. 


parser3,y (Rules Section) 

nr program 

nL_0tatement_l1st nt quit statement 

I 

gProgramP = $1 >Append($2): 

YYACCEPT; 


//code omitted 

nt_ a s s itatsmen i 

T SET_ I IDENTIFIER T_GETS T„SEMIC0L0N 

t 

$$ s new CSetAssignNode($1, $3); 
l 

I 

T_W U MB ER_ I DENT I FT ER T_GETS nt_rmtnber T SEMICOLON 

I 

$$ = new CNueiberAssignNcKle{$1 * $3): 

1 

I 

//code omliied 


//code omitted 
nt end if 
T_ENO 

I 

T_END T_1F 


//code omitted 

nt_number. list 

Z* empty 7 
l 

$$ = new CNumberList() : 

1 

nt number_lifit T_COMHA nt_number 
l 

$$ ” $i->App*nd{$3); 

I 

//cock omitted 

The nt_program rule appends the nt_quit_statement to 
a global CStatementUst* (a global variable is the standard 
way in which information from yyparseQ reaches the 
outside world) and then uses the macro YYACCEPT which 
causes the parser to return a value indicating that the 
input was acceptable. 

The nt_assigu_statement rule reductions demonstrate 
ilie usual rule structure. We pass the right-side non¬ 
terminal and token values to the constructor of an object 
for the left side. This makes writing the class constructors 
exceptionally easy, they are almost completely dictated by 
your parser specification. 

The section of code for an nt_number_list shows how 
lists are generated. The list is created with a default 
constructor (from an /* empty V non-terminal) and then 
following nodes are appended to the list. 

One thing to notice is that there are a lot of new 
statements and not a single delete. The CNode class and 
Us subclasses take ownership of pointers passed to them 
and guarantee that these nodes will be deleLed (through 
the use of an auto_ptr style template class). Furthermore, 
CNode is designed so that it cannot be allocated on the 
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stack and so die call to delete will always be to a pointer 
originally created with new. This type of care is necessary 
in generating parsers with flex and bison because you 
don’t typically know how the flow of control moves 
through the resulting source code. And because your 
parser may be required to deal with hundreds (or 
thousands) of tokens and non-terminals in a single run, 
losing even a liute memory for each one can result in 
severe memory problems. 

Processing the purser specification 

When you issue the Make command* the parserS.y 
specification should generate a parse r3,tab,c source file 
and this file will compile without error. You should get a 
link error (_ start hasn't been defined since we don’t have 
a main() function). One thing to be careful abmn here is 
lhat tr is very easy to try and fix your C/C++ errors in the 
compiler Errors & Warnings Window. This is a mistake since 
the next time you process the parser specification* you 
will overwrite the file with your fixes. Personally, 1 do 
tend to fix die compile errors in the Errors & Warnings 
Window (making a note of what I fix) and once 1 get a 
clean compile, I go back and fix the code in the 
specification. This is because (being really impatient) I 
don't want to wait while bison runs after each fix to see 
if the fix was correct. You just need to remember to go 
back and change the parser specification before you run 
bison again. Now that we appear to have a source file for 
the parser* it is time to try to build the first application* 

Parser 4 

The Abstract Syntax Tree 

There’s nothing terribly tricky in the CNode 
subclasses* You might want to peruse some of the source 
files to convince yourself that they do what I say they are 
going to do* The classes are really skeletal in the sense 
that they provide no facilities to interpret Lite Miniset 
language. If we were going to implement the interpreter, 
1 would have added Execute/) methods to the 
CStatementlModes and Value{) methods to die 
CBooleanNodes, CNumberNodes and CSetNodes. 

Adjusting the parser specification 

There are very few changes if) the parser specification. 
The first is to provide access to the scanner created by 
Hex. Unfortunately* all the source files front Ilex will be 
called the same unless we enable the Gen, prefix from file 
name option in the Flex preference panel which will cause 
the files to be labeled uniquely. The downside to this is 
tintt all of the scanner functions will also lie named 
uniquely, so we need to provide some glue. 

parser!,y (Definitions Section) 

namespace t 

inline Int yylex(void) I return KCann«r4tex () ; f 

] 


Tliis is needed because the yyparseO will call yylcxO. 

Tire second change is to have the parser print out any 
top-level statement it encounters just fxdbre appending it to 
Lite statement list being created 


parser!.y (Rules Section) 

//code omitted 

n t _& t a temeu t_I1st 

/* empty */ 

i 

$$ - new CStatementL f at 0 ; 

I 

! 

ni_ma nrestatement 

1 

$$ ~ $1 ->Append E$2); 
std;:cout << std::endl; 

$2->PrettyPrini(std:scout , I); 

std : scout << rrrd : :end1 : 

1 


//code omitted 

The last changes are to the user routine section. First, 
we add the definition of the global variable gProgramP 
which is used to pass the result of the call to yyparsefi to 
the outside world. We also add a very rudimentary error 
routine called yyerror() (which will be required by both 
tlte parser and the scanner even if you never call it in 
your own code). The error routine just prints out a short 
(and not very informative) error, better error handling is 
implemented in Parser 7, 


Writing the scantier specification 

The scanner specification (in scanner4.l) is all that remains 
to discuss. The Ilex plug-in will take a scanner spedFtcation and 
generate the code needed for l lie function yylexf) (or in our 
case scanner4lex()). The specification has the same layout as the 
parser specification with a Definitions Section, a Rules Section 
and a User Routine Section* These sections serve rhe same 
purposes as the sections in tlte parser s| Re ification. 

SO* 111 !lt 4 .111 Kfini tttu th Sc (.lit in) 

%l 

#include “parser*h" 

//include “parser4* tab. h" 

tfifdef yywrap 
// undef yywrap 

//end i r 

inline int yywrap(void) I return 0; I; 

(/define YY NEVER INTERACTIVE 1 
ffifdef YY INPUT 

// undflf vvjwirr 

//end i f 

//define YV_lNI J UT(inBut fee, out Result, inMaxSize) \ 

((outResult) = FillBuffer{(inBuffer}* (inMaxSize))) 

namespace i 

const IongrheftyfTerSize ^ 8*1024: 
char thcRuTier[LheBufferSizeJ ; 
long theChaxCount: 

inline int FillBuffer(char* inBuffer, 1 nr inMaxSi^e) 
t 
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heaviest traffic in New ¥>rk City 
and loving every minute of it. 


This year at Macworld, Apple is going to make it easier for till developers, big and small, to have a 
space as special as their ideas. Apple Developer Connection and MacTecb" Magazine present 
Developer Centcaiman exhibit at Macworld that showcases developer tml/service companies 
developing for the Macintosh in the biggest possible way Macworld will be held in New York City, 
July 18-21,2000. Check out the exhibits at the show and on the web at: www.devcentral.com 


ADC 


Apple Developer Connection 



d JOOaAf)pteCmpnk% iuv. art n0s trscrml fypk fitw dw&tfwf w niyntmt fmkuunhs. 

flttiilr r (ijjavtit ts a imkmmif ^ -tyjdv CaniftukK im Mat 'tixb *s o u.’gnkHti tuith’tmnl- ^ Xj&tia OjtjrmtikM 







VapthepovurofAppleScyipt 
witb Main Svamrs ScripUrt 


For professionals and novices 
Webmasters and solution providers 

No matter what your experience, 
Scripter makes it easier! 


if (0 — theCharCenJtyt) 

f 

std::cin.getline(theBuffer, theBufferSize): 

// -I since we consume the \n, 

//but is not i m liklt tl in theHurfer 

theOharCounL = sid : :cin . gcountO 1; 


hit tkeFillSize = ( (inMaxSize < theCharCount) ? 

inMaxSize : theCharCount ): 


if {theFillSize > 0) 

t 


I 


std : : nsemepy ( inBuf For ♦ LheBuffet, theFillSize) ; 
theCharCount -- ihei'ill&ize; 

std t memepy (theBuffer , theBuffer + theFillSize, 
theCharCount); 


return theFillSize; 
I 

J 

%} 

DIGIT EL0'9j) 

UCHAR C[A-Z]) 

LCHAR ([a z]) 

USCR ([_]> 

CHAR ([A Za -x_J) 

MS ([\t\n\r 3 ) 


BEGINNER AT SCRIPTING? 

• Unique command-builders help you learn to 
assemble commands 

• Built-in tools for experimenting 

• Shortcuts to speed scripting 

EXPERIENCED WITH APPLESCRIPT? 

• Unmatched single-step interactive debugging 

• Watch and modify global and local variables 
while stepping 

• Debug messages sent to script applications 

• Includes ScriptBase to integrate scripting scenarios 


In the Definitions Section, we shirr by defining some of die 
macros and functions needed by the parser. The yywrap{) 
function is defined to return 0, indicating that die parser can 
always expect more input (there will be no end-of-file since die 
user will l>c supplying it from the console window). The 
YYJNPUT macro is used to fill Ilex’s internal buffer of the stream, 
the RIlBuffer function (in an unnamed namespace) serves this 
purpose for us by calling getlinefl on std::cin. 

The remaining lines declare abbreviations for commonly 
used characters (digits, uppercase characters, lowercase 
diameters, underscores, all characters and whitespace). The 
complete description of regular expressions is beyond diis 
article, but a quick overview of those used here are: 

* Characters in square braces [ ] indicate one of the 
included characters 

• Cltaraclers followed by a * indicate zero or more occurrences 


Scripter received MacWeek's 5-diamond rating - Twice! 
"Scripter's virtuoso display of AppfeScripting savvy and 
debugging wizardry make it the best environment we've 
found for homing or creating AppleScript scripts /' 

—Mac Week 


Hake AppleScript and your 
applications work for you) 



Main Event 
PO Box 21470 
Washington, DC 20009 
Tel: 202-298-9595 
Sales: 800-616-8320 
info^maineventcom 
www.maineventcom 


* Characters followed by a + indicate one or more occurrences 

* A period (.) indicates any character other than a newline 

Each token is associated with a block of C/C++ code. 
Just as in the parser specification, this code will lx* executed 
when the token is matched. 


scanner*.] Section) 


[ return T COMMA: I 
{ return T SEMICOLON; \ 

“ (** I return T_0?RN_FAREN; I 

1 return T_CLOSK_FAREN; ) 
end { return T_KN0; I 
if \ return T_IF; J 

elif 

ei&eif 1 return T ELSE IF; J 
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Display and Tradsshow 


• Award winning strategy, graphics team, and certified consultants 
to assist at every phase 
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Where Your Tradeshow Success Is By Design! 

www.lasercolor.com 

email: support@lasercolor.com 


Tradeshow y/lZ 


• On-line virtual tours of your exhibit and graphics, 
for year-round tours 


• Interactive displays, exhibits, kiosks 


• Multi-sensory graphic capabilities 


• Creative, result-oriented print packages 
for pre/during/post show mailings 


• Specialized in multi-configurable, modular 
exhibits, and portable displays 


• Motion posters, special lighting, 
sound, costumes, giveaways, etc. 












//cock- omitted 
I DIGIT 1 + I 

yyiva I * Number 3 new CNurabetLiteraitiodetyytext) ; 

return T_NUMRE R_ LiTEKAL: 

I 

IUCHARMCHARI* I 

yylval.Identifier = new Cldetitlf lerNodetyytext); 

return T_SET IDENTIFIER; 

I 

//code omitted 

[WSJ* t /’ignore whitespace*/ f 

"//*•* I /‘ignore comments*/ I 

* f yyerror("Bart Character ")i I 

In general, Mur C/C++ code simply returns the token 
type to the purser us in the case of a comma, a semicolon 
etc. Symbols are enclosed in double-quotes to remove any 
special meanings. If the rule for a symbol is a vertical bar Cl), 
then the rule lor the following token is used. For example, 
both "eliP and “elseif* produce the token T_ELSEJF. 

The rules for number literal tokens and identifiers 
need U) do a little more work. These tokens provide more 
information than just the type of the token scanned, the 
parser will also need to know the value of the token. In 
each case, we construct a node of the appropriate type 
and assign it to the variable yylval. The type of this 
variable is equal to Lhe union defined in the file parser4.y 
and we need to assign the information to the appropriate 
union member. The scanner variable yytext contains the 
text ul the token scanned. You will need to copy yytexl if 
you wish to use it outside of the action block. 

finally, white space and comments are ignored. File 
scanner will scan them, but without a return statement in 
the code block, the parser will never see them. The last 
rule matches any other token and calls the function 
yyerror (defined in parser4.y) which will print an error 
message and hall the parse. 

Writing main 

Ignoring the debugging code, main is short and simple. 
We parse the user input until it completes a program or there 
is a parse error. II a program is completed, we echo it out, 
otherwise, we print "Program Incomplete*, 


std : 

: rout 


H Program Complete" << std:;endl; 

st d : 

:rout 

« 

- -" « std :: endl: 

std : 

: cou l 

« 

std::endl: 

BPro&iaraP- >PrettyPrlnt (std : :eout, 1 ) : 

i 

else 

i 




i 

std: 

: tout 

« 

std :: endl; 

std : 

: cout 

« 

—" « std::endl : 

std : 

: rout 

« 

M Frogram Incomplete" « Atd::«ndl 

std : 

:cout 

« 

" ■" « std::endl; 

std : 

:cout 

« 

std ; : endl ; 


1 

I 


Kun n mg Parser 4 

We now have something we can build and run, so 
issue Lhe Run command. The target already has a number 
of debugging settings selected. In particular, Generate 
debug scanner is selected in the Flex preference panel and 
Generate Debug Parser is selected in the bison preference 
panel. When the parser asks if you want to create a debug 
parser, answer with anything other than y. We will use a 
debug parser in a moment, but not quite yet. 

The output included in parentheses stalling with —* is 
feedback from the scanner. Start with a simple assignment 
statement, for example, type 

x £ - 2 ; 

and press return. The parser should accept this as a 
complete statement, but the parser complains of an 
“empty buffer* and requires you to type Lhe next line 
before echoing the first statement. 

If you want more feedback, quit Parser 4, restart Parser 
l and type y at the start of the session. Thus will turn on 
the debugging code in the parser and now you will be told 
what the parser is doing as well as the scanner. If you do 
lliis, then you will see that the parser geLs the 2 as a 
number literal, but then before the- parser sees the 
semicolon, the scanner responds with the "empty buffer* 
message. The problem is that the scanner needs to know 
that the token (starting with the semicolon) is finished 
before it can decide what to do next. I In fortunately, when 
the scanner tries to read ahead, it finds that the buffer is 
empty and so it calls our Fil(Buffer() routine which waits for 
another line of input. This is why we will need to type a 
new line before the semicolon gets processed 


muin.q? 

ittt main(void) 

I 


//iX-foujjj’inj; code omitted 

std::cout << “Enter some mini sol code:’* << std::endl: 
std;:cout << £td::enrtl; 
int theRpflij 1 1 = yyparsot); 

if (0 theKesttlt) 

I 

sld : : cout « std::endl; 

std:: trout << *--" << std:: endl: 
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fau won't believe what you can do with ReplayTV. It's not a VCR, it's a digital television 
recorder, so you can actually pause live television, and do your own live instant replays. 
It also has a search engine, so you can punch in a keyword, say ''Golf," and it will find and record 
arty golf program that comes on—all without videotape. Or you can just punch in the name 
of your favorite show and let ReplayTV find it and store every episode, so you'll never miss it 
again. If you had ReplayTV, what would you do? Call us at 877 'replaytv or visit www.replaytv.com 


Available at Best Buy, Circuit City and Amazon.com 
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Parser 5 

Adjusting the scanner specification 

The new line at the end of the command should lie scanned 
as white space, hut we have discarded it when we called 
getfineQ in the FilfBufferQ routine. We simply need to acid it 
back into the Buffer manually. 


parsers.y criHHiiffcr) 

inline \nt FillBuffer(char* inRuffer, Int inMaxSiza) 

If (0 — theCharCount) 

I 

std: :ein. get line UheBuffer. tfeeRuf ferSiae Dr 

thaCharCouni ~ std; :cin. gcotintO ; 
theBuf fet [ LheCharCount - 1] * *\n'; 
t-hpRuf fer [theCharCount] w '\0* ; 

I 

int theFillSize = { (InMaxSize < theCharCounL ) 7 
lnMaxSize ; theCharCouriL }; 

if (thoFil \$Ue > 0) 
t 

stti: : memepy CinBuffer . thoRuffer. theFillSizp); 
f heCharCount theFillSize s 

at d ::memc py(thaBu ffer. 

th^Buffcr + theFiilSiza* theCharCount); 

return UieFillSIze; 

I 


Running Parser 5 

That’s enough work on the scanner. Ai this point, I 
believe we are down to one bug in the parser. Because 
we will be debugging the parser, the Verbose option is sei 
in the Bison preference panel so that we can use the 
parsers.output file if we need it (I predict we will). Issue 
the Run command and type y at the first prompt and try 
to define a non-empty set: 

x <- t I. 2. 31 i 

This will lie unsuccessful, and the parser will give you more 
information than you probably want. The article presents the 
few lines which are of most interest. 


Parser 5 console output 

Shifting token 277 (TJ3PEN_SET), Entering stare 8 
Reducing via rule 56 (lino 427). -> nt *«mber_list 

state stack now 0 1 12 44 8 
Entering state 42 

Reading a token: Next token is 279 (T.NUMBER^LITERAL) 
!Urk: parse error 

The error occurs when the parser hies reduced an r empty 7 
to an nt_number_list anti sees the first number (in this case a 
TJ\iUMBER_UTERAU This causes a parse error and the 
stack is popped since we have no error handling 


mechanisms. The important information is that the parser 
was in state 42 when the I MUM BE RJJTERAL was scanned. 
We would expect that a T_NUMBER LITERAL would be valid 
at Lhis point, so lets sec what state 42 thinks is valid 


parser^, output 

state 42 

tit_set ■> T_0FEN_SKT nt_number_list * T CL0SE_SET 
(rule 53) 

nt_numbnr list > n t_u«mb«r_li f,t . T_C0HMA ttt_number 
(rule 59] 

T .COMMA shift, and go to tfta1e /l 
T_JXQSE„SET shift, and go to state 72 

The first possibility in state 42 expects a T CLOSE_SET 
and in this case rhe parser will reduce ;m nt_set (in our case 
an empty set). You can check that tills works correctly in 
Parser 5. in the second case, the parser expects a T_CGMMA 
followed by an nf_nymber in which case it will reduce an 
nt_numberJist. Since we want the list to be extended with the 
next number, this is Lite case on which we will focus. 

First, we confirm that we have found the problem by 
testing the statement: 

X < I a* 2. 3 I; 

Parser 5 aecepts this as valid, but then echoes: 

x <- { 1, 2,3 d 

You can confirm that the parser exhibits the same 
behavior with parameter lists and expression lists but 
behaves correctly with regard to statement lists. The 
problem is that the first number in a number list 1$ 
different from every other number in the list because it is 
not preceded by a comma (equivalently, the last number 
is different because k is not followed by a comma). In this 
way, the comma is a different type of punctuation than 
tlie semicolon (the former is a separator and the latter is 
a terminator). We will now make the parser specification 
appreciate this fact. 

Parser 6 

Adjusting the parser specification 

One method for solving this problem is to create a 
new non-terminal and expanding the rules for these lists. 
The new non-terminal is for an nt nonempty_numberJist 
and parser will be able to identify whether you want the 
empty or non-empty version by checking the look-ahead 
token (if it is an nLnumber. the list is non-empty). The 
specifications for nt parameterJist and nt expression Jist 
are also adjusted in a similar manner. 


54 


Using Flkx and Bison 


MacTeui • July 2000 














pVPCHAS e SoFTMfce 
ujfTH A Click 

OF A... UJtfeF, THAT 

*JA$F*ZT7 


r 


A 

[ j 



L 


J 


e s e 11 e r a t e 

Another way to sell softwore 
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piirscrfry (Rules Section) 

nt number lint 

r empty 7 

t 

$$ = new CNumberList 0 i 

* 

nt_ftonempty number_lisi 
i 

$$-$!; 

I 


nL_tionempty_number list 

nt_iunnb«*r 

I 

$$ ■ new GNLiiiiberList:($1) ♦ 

I 

l 

nt.nonempty^number list T_COKWA nt.number 
I 

$$ - $l->Append($3); 


Running Parser 6 

Congratulations, you have now worked through the 
process of constructing a parser You can verify that all the 
lists act as expected and that all the other hugs we hunted 
down earlier have lx^en correctly resolver) (e.g,, operator 
precedence). The next two targets add some amenities, hut 
the hard work has been completed. 

Parsers 7 & 8 

At this point, Eve run out of words Cor more correctly* 
the column has run out of space). Parsers 7 and 8 are 
slightly more complex than Parser 6 and provide some 
extra amenities. If I have intrigued you with the idea of 
writing your own parser, you may want to pick up 
Levine's hook or the bison and flex manuals and see if 
you can understand vvliat 1 have done in these last two 
targets. I describe some of the added features next. 

Parser 7 

Parser? recovers from syntax errors moregracefully than 
just aborting. It will discard everything back to the last 
complete statement and then ask die user to continue from 
that point. While this would probably be unacceptable if 
Miniset were designed lor batch compilation, the strategy is 
appropriate for an interpreted language. 

Parser 7 also adds some rudimentary error handling. In 
particular, it catches the mistake of using the wrong type on 
the left side of an assignment statement. For example, 1 
frequently l ind myself typing: 


k < I 1. 2, II: 

but in Miniset this a type* error (x is a number variable 
because it starts with a lowercase letter). 

Parser 8 

Parser 8 doesn't enhance the user's interface with Minisci, 
but does help the progamming interface. Parser 8 encapsulates 
the whole parsing mechanism into a C++ class. The class Is 
implemented in the files CParser.cp, scannersJ and parserQ.y with 
all interfaces in the header Hie CParser.h. Although all methods 
of the CParser class are static, we could set up flex and bison to 
avoid the use- of global variables and make separate CParser 
objects. 1'his would be important if Miniset were Ixnng run on a 
server with each user working with a separate CParser 
instantiation. Parser H also allows the user to take input from a 
file instead of from the keyboard “Ibis is used to create a 
consistency check on the scanner and parser. Once a program is 
completed it is printed to a hie and then reparsed and reprinted 
to a second file. The resulting two tiles should lx* identical 

Where To Go Now 

If litis intrigues you* the first thing to get is the Ilex and bison 
plug-ins at <http;//www.ambrosiaSW.conV-fprefect/plugins,html> 

you can gel bison documentation at: 

<http://www.gnu.org/manual/bisori/indexjitml> 

and I found Ilex documentation at: 
<http://www.deiorie.com/gnu/docs/flex/> 

If you've got some money, the lx-*st introduction to flex and 
bison is probably the Ixmk lex & yacc by John R. Levine, Tony 
Mason and Doug Brown. O’Reilly & Associates, Inc printed the 
second edition in 1992 (with minor corrections in 1995X 

You might also want to hx>k into the Purdue Compiler 
Construction Tool Set (PCGTSX These tools are an alternative 
to Ilex and bison ami you am find information about them 
at <htrp://www.antir.org/> 

Even if you stick with Hex and bison, the section “Exactly 
1800 Words On Languages and Parsing" in Language 
Translation Using PCCTS and C++ (free for download from 
at the URL given above) is worth reading if you are interested 
in some of the theory behin d gr ammars. ffitS 
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PROGRAMMER'S 

CHALLENGE 


By Boh Boonstra, Westfonl MA 


RAID-5+ 

Those of you in the Inforn union Systems business have 
certainly heard of Redundant Array of Independent (or 
tnexjxmsive) Disks, or RAID technology. As ltic name suggests, 
RAID stores data across multiple disks to provide improved 
performance and some level of protection against disk failure. 
Several RAID levels have been implemented, and one of the most 
common, RAID level 5, employs disk striping (spreading blocks 
of data across multiple disks) and parity to optimize disk access 
for applications that perform random small read/write operations, 
and to protec t against the failure of a single disk. 

Our Challenge application, however, is a little more 
demanding. Were operating a mission critical application, one 
that cannot afford to lose data even with a double hardware 
failure. Your Challenge is to implement a KAID-5+ system that 
has the performance advantages of RAID 5, but can continue 
functioning when two disk drives fail 

The prototype for the code you should write is: 


r 

“ RtfulPitic nodWriseFnx; art callbacks that aJIow you tu write in multiple driven 

" sinmltancoualy, “Emulating Un- effect of striping. 

7 

f\jvA&i void (* Wr I Lt??i ■ (F conduct physical writes to rmillipk drives 7 

1 : g stri r tBy t {] * F Mart write fa>m staith>ie|a| physical hyte on disk n 7 

i : i g numEy t ■ ■■•?(]. t write numhytcsfil | bytes from disk n 7 

ha r T vri l e Buffer II. F write to bufferl n ] fa>m diwk n 7 
Boolean readErrU 

F returns wriurlirrinj-=mie if disk n ha* ;t write emir nr paramcim were had 7 

h 

i ypeck< i void [ * Read Pro c) \f conduct physical reads from multiple drives 7 
long startBytn [ 1 * /* Mart read from startbyie|n] physical byte on disk n 7 
r bvies si art Byte. sLirtbyie+numBytes-l must lx: within 0..diskSizcl 7 
long munfly Us []. F rcrud mi mbytes] n \ bytes from disk n 7 

har 1 end Buffer 13, /’ read into bijJTcr|n| from disk n 7 

Boolean readErrf] 

t at urns readErr|n]—imc if disk n I us a read error or parameters were had 7 

}; 


F 

I nit Raid provides the problem parameters 

7 

void TnltJUudt 
long mmiDisks* 

t problem size, you will haw numDisb of real data, plus l disks for parity 7 
1 orjg d iskSl ze . F numixr of bytes in each disk 7 

long failureRai ., t expect I failure in each GtilureRlle reud/write attempts 7 

Write?roe phyaieaiWrite. 

F procedure dial allows you to w rite to numDtsLs+2 disks of sire dlskSi/c 7 

Read?roe pbysicalRead 

F pmcedure dial allows you to read from numDisks+2 disks of si/e diskSi/e 7 


void KepairDifikf 

long whichD 5 nk t ffkJcx of disk that has beat apjiraxf.no more than 1 at one time 7 


r 

' Raid Write and KaidReud ask you to write lo die nunilfisksMisksi/c bytes of 
1 storage. You use WritePmc and Read pnx to actually write lo the ( nunil>Lsks+2) 

1 physical devices, using mlundani w rites to compensate for die loss of up to two 

* disks RaidWrile and R.iidKead bytes are numbered it numDisks J diskSi/c l 

* RaidWrite and RaidHcad alum true unless there is a problem performing the 

* write/resd. 

7 


Boolean RaidWrite( 
long atartByte, 
long numBytes, 
char 'buffer 

k 

Boolean RaldRcadt 
long fmir tbyte, 
long munBytes„ 
chat 1 buffer 

k 

void TerraRaid[void): 


F w rite starting at this hyte 7 
F number of bytes to write 7 
r write bytes from this hiiffer 7 


F read starting ai this byte 7 
F number of bytes to read 7 
F lead bytes into this buffer 7 


This Challenge starts with a call to your InitRaid routine. 
InitRaid is provided with the number of disks (numDisks) 
available to your Raid 5+ implementation. Actually, numDisks 
represents the amount of data you need to store and protect; 
you actually have numDisks+2 disks available, with the 
additional 2 disks used to provide protection against disk 
failures. InitRaid is also provided with the si/e of the identically 
sized disks in bytes ( numBytes), and the approximate failure rate 
of the disks (1 failure in failureRate read/write attempts). Finally, 
InitRaid is provided with two callback routines that provide you 
with read and write access to the phy sical disks in our simulated 
disk array, which well discuss below. 

The Challenge evaluation consists of a large number of 
RaidWrite and RaidRead operations. Each RaidWrite call 
provides a logical address to write to (startByte) in the range 
0.,numDisks*diskSize-k a number of bytes to write (numBytes), 
and a buffer from which to write. Your code must write the data 
to the simulated disks provided using the WriteProc callback, 
providing for error correction by writing redundant information 
to other disks. If WrrteProc returns a writeErr[n] value of true, the 
write to disk n failed, and you may need to compensate. 
RaidRead provides a logical address to read from, a number of 
bytes to read, and a buffer to read into. If ReadProc returns a 
readErr[n] value of true, the corresponding read operation 
failed, and you will need to use the redundant disks to 
reconstruct the lost information. 

At the end of I he evaluation, your TermRaid routine will be 
called. You should free any memory you have allocated. 

From lime to time, a failed disk may be repaired. You’ll be 
notified of such a repair by a call to RepairDisk When a disk is 
repaired, you ought to reconstruct any necessary error 
correction information, because another disk may fail at any 
time. Up to two disks may be in “failed" mode at any given time, 

WriteProc allows you to perform a write operation on all of 
Lhc disks in the array simultaneously, writing numByte$[n] from 
writeBuffer[n] starting at physical location startBytefn] on disk n. 
Similarly, ReadProc allows you to perform a simultaneous read 
operation on all of the disks, reading numBytes[n] into 


58 


Programmer's Challenge 


MacTech ■ J i tv 2000 












readBufferfn] starting from physiail local it >n startByte[n] on disk n. 
Unfortunately, the disk controllers in our simulated system are 
not very sophisticated: while disk I/O occurs tn parallel, our 
disks an: not able to chain sequential t/O operations. An I/O 
operation on the array requires read/write time proportional to 
the hugest numBytes[n] value passed to any disk. 

Our disks will have, say, 5msec average seek time, and 
30MB sec transfer rates. Your program's score will lie the sum 
of the seek and transfer Limes for each read/write operation, 
plus the execution time required by your program. The winner 
will be the solution that correctly performs all read/write 
o[xrations with the lowest program score. 

There are no specific memory restrictions on this Challenge, 
but you may not allocate memory to store all of the data written 
to the simulated disk array, or to jXTsistently store any error 
correction information. You must use the simulated disks and 
the WriteProc and ReadProc callbacks for that puqx>se. 

This will l>e a native PowerPC Challenge, using the 
QxleWarrior Pro 5 environment. Solutions may lx* axled in C* 
C++* nr Pascal. 


Thrff Months Ago Winner 

Congratulations to Ernst Miinter (Kanaia, Ontario) for 
taking first place in the April Text Compression Challenge* 
l itis Challenge required contestants to process input text anti 
compress it into as few bytes as possible, while minimizing 
the execution time used to perform the compression. The 
input text consisted of English-language text; computer 
programs written in C, C++, or Pascal; and web pages written 
in html. Scoring was based on the number of characters of 
compressed text, with a 10% penalty added for each 100msec 
of execution time, Ernst's entry was the not the fastest of the 
5 correct entries* but it did produce the most highly 
compressed output. 

1 used 17 test cases to evaluate the entries* including H text 
hies, 3 computer programs* and 6 web pages, totaling “5.6MB in 
length. Individual inputs ranged in size from less titan 100G bytes 
to just over 1MB. Erast’s solution compressed these inputs into 
about 35% of their original size. While l didn't independently 
verify this, Ernst observes that his code produces a smaller result 
for a large text file than a popular Mac compression utility* and 
does so in less time. 

The three entries producing the smallest output all used a 
variant of Huffman encoding. This technique assigns bit 
representations of varying lengths to individual tokens in the 
input* with shorter Huffman codes used for tokens that occur 
more frequently. Ernst took the additional step of assigning a 
token code to each input token, and then compressing the token 
codes using Huffman encoding. This approach resulted in -50% 
better compression Ilian that achieved by Jan SchoLsman’s next 
best entry (although Jan's entry was submitted after the 
Challenge deadline and not eligible to win). 

The table below lists* for each of the solutions 
submitted* the cumulative size of the input text and output 
texts, the execution time in milliseconds* the total score 


Instead of ItiniHg around your house 

run your house with this. 

Lev I ton’s Touchscreen Decora Home Control center uses 
advanced graphics interface technology to take the mystery 
out of home automation. T he 
result: total control over 
lighting* heating, appliances 
and much more* all from a 
system as easy to use as a 
telephone. Simply plug the 
touchscreen into an electri¬ 
cal outlet and control 
Levi Lon's acclaimed line of 
DHC switches* dimmers, 
receptacles* thermostats, 
and more, ft’s an automation 
system that’s as easy to add as it is to use* because it uses 
the existing electrical wiring as a command network wilhoul 
any special wiring. 


LlWJi3 \ 

Nrnin. & 


semyea l « 0 p 

o*. 

h 

esTi[ 

•X-PtJER LfrftP 

of c 

1 \ 

. ■. 

i»-k| 

TRr-CH. .LlfHF- 


•i. 

of*] 

iij'jyy 

is!j 



‘ .ij iijii 

.jfi 


' - -; 


3S 


JT ; 

HE1J 1 p-ETWrC' 

• hwfj • 




lim 


< h 



Levitan's Decora Home Controls with 
Touchscreen Control Center are just 
one of the timvations in integrated 
Sokitkm for System Designers, 
for more information or the complete 

lewlon Integrated Solutions at 
{800} 8770190 extension 789. 
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Bm'Wirfy A Cviiiu'ffrrf WoHd 


Hanging around art galleries and 
fflUSeUST could give an ordinary 
lighting Control delusions of grandeur. 

Fortunately, Levitor+s Monet T * 
dimmer is no ordinary lighting 
control. It’s a work of art In itself, 
designed to associate with some of 
the best. Designed for use in show¬ 
rooms* galleries and museums* this 
architectural specification-grade 
dimmer is now showing in selected 
home environments as well. Pre- 
programmable scene control and 
alLdigital circuitry can call up the 
right mood for romance or the best 
background for home theater. Most 
important* Monet’s beauty is more 
than skin deep. It's a direct descen¬ 
dant of the Levi ton professional 
lighting controls proven in years of 
demanding commercial use. 




sOiffuons 

tewftwfc Mrm dimmers are/usroneof 
Hie movatms in integrated Sotutiom for 
System Designers, for more information 
or the complete resource on CD-ROM, 
contact Lewtfln frtfegtefed StiJc/ttons at 
i800) 8770190 extension 789 . 
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achieved lor all test cases, ft also provides the code size, data 
size, and programming language used for each entry. As 
usual, the number in parentheses after the entrant's name is 
the total number of Challenge points earned tn all Challenges 
prior to this one. 


Input Output Time Scon: Code Dma tang 


Size (KB) 

Si/e m) 

(msec) 


Si/c 

s tec 


Krnst Muntci (SHTJ 

5595 

1912 

1865 HO 

2327(137 

«7<H 

1216 

O* * 

Kandy Boring (123) 

5595 

4896 

256.35 

51867M 

1504 

56 

C++ 

Sebastian Maurer (101) 

5505 

5142 

1482.87 

5512646 

532K 

1394 

C++ 

Annin Sdimidi 

5995 

M07 

2112.08 

5824H96 

2400 

m 

€ 

Jan Sclvotsman (late enny) 

5595 

2207 

58-15.J3 

3928065 

15060 

320 

C 

) T. 




crash 

16340 135H6 

C 


Top Ointhstants 

Listed here are the Top Contestants for the Programmer's 
Challenge, including everyone who has accumulated 10 or more 
points during the past ivvo years. The numbers Mow include 
points awarded over the 24 most recent contests, including 
points earned by this month's entrants. 


Rank 

Name Points 

Rank 

Name 

Points 

T~ 

Muntci; Ernst 

243 

10, 

Downs, Andrew 

12 

l 

Saxton, Tom 

139 

IL 

Jones, Dennis 

12 

3, 

Maurer, Sebastian 

78 

12. 

Duga, Brady 

JO 

4, 

Boring, Randy 

56 

13- 

Fazekas, Mi kins 

10 

3, 

Shearer, Rob 

47 

14. 

llewett, Kevin 

10 

6, 

Rieken. Willeke 

41 

15. 

Murphy. ACC 

10 

7, 

] Iciliicot'k, JG 

33 

16. 

Sdengut, Jared 

10 

8. 

Taylor, Jonathan 

26 

17. 

Stroui, Joe 

10 

9. 

Brown. Pat 

20 





There are three ways to earn points: (1) scoring in the top 
5 of any Challenge, (2) Ixdng the first person to find a bug in a 
published winning solution or, (3) being the first person to 
suggest a Challenge that I use. The points you can win are: 


1st place 

20 points 

2nd place 

10 points 

3rd place 

7 points 

4th place 

4 points 

5ih place 

2 points 

finding bug 

2 points 

suggesting Challenge 

2 points 


Mere is Erasts winning 'text Compression solution: 

TextCom pression.cp 
Copyright € 2000 
Ernst Miiiiier 

r 

'lkxk 


Find and implement m efficient ilgorkhm m compress and expand text. Efficiency 
is ;t compromise [>ctwecn compression factor and s|wred 

Algorithm 

The algorithm ts bused on the rccugnilhm that text wilt consist of altcrruling ,, word^ 
and* I ink' I ragmen ts Word fragment* arc character sequences Irum one character 
set, links are sequence* from a non-overlapping different set. 

Each of tlte two sets contain 64 characters: alphanumeric* + two extra characters 
( _ and # ) to make up tile word set. all others full into the link set 

Many of the fragments will be encountered only once, others many limes. 

The compressed text is primarily a sequence of tokens, where each token represents 
a fragment, or introduces it new fragment. Each fragment is defined explidldy only 
i lie first time it is encountered. It ihc same lexical fragment occurs multiple times in 
the text, a token code definition is generated lor this fragment. Subsequent 
occurrences of the same fragment arc then “quoted" by their code only 

Token ( rales are Huffman encoded. As a result the codes tbr frequently iK.cureiiijt 
fragments (such as (lie single space between words) arc coded witty fewer bit* than 
less frequently repealing fragmcnLs.Twu codes are reserved as Hags, one for 
introducing a fragment which only occurs once in the lexica second for imreMlncing 
a multiply occurring Jmgment plus its associated code 

Implementation 

Compressor 

The text is parsed into words amt links A token cache tracks unique fragments, and 
records Iheir frequency. At the same time, a quotes list is built, one quote (token 
piiriLer) for each fragment 

Actually two caches ami token sets are created, one for word fragments and a 
separate one for link fragments 

Hie next step is die creation of the Huffman codes fur each token.To this end, all 
tokens with a frequency > J are- preshed on a heap (priority queue), A Huffman tree 
is built witli intermediate nodes each holding pointer* to two child nodes. The leaf 
nodes are the token records Traversing the finished tree from the root then 
provides the mechanism of assigning each tea I node (token) its code. 

Finally, the list of quotes is scanned.and each token or token code placed in the 
i ranpressed text array, 

A' bit Pump’ object provides a method of dealing with arbitrary hit si/e chunks 
The bit ptunp also provides the packing (and unpacking} of the tirigiiial S-hit 
characters into 6-biis. 

Expander 

Hie expander reads a few length parameters from the compressed text header ami 
then precedes to read the compressed text hit by bit to decode token codes. At the 
''tart il is given only the codes for the two flag tokens Then, eac h previously unseal 
emit and fragment is introduced as needed, preceded by a flag eodc 

Flic two Huffman decode trees (fur decoding worel anti link loken codes) are thus 
built one code at time, juM-imime, and linked to the decoded fragments which are 
placed directly into the expanded next 

Optimizations 


List ol possible optimizations considered but not applied 

- more efficient Huffman decoder 

* recognize capitalized words as "the same" and Hag 
nst 1 a fixed dictionary of likey words, and provided default 
token codes lor diem which then do not need to he made explicit 
more efficient bit pump 
Huffman code the fragment characters 

- do run-length coding where it pays off fe g. multiple spaces) 

All of these I'an bring additional small percentage Improvements in compression at 

the expense of added complexity and time I have decided to keep il simple. 

Compiler Notes 


One would expect the compiler to inline simple chess methods such as 
im SingkThtgO | ret uni &tokcnfb};| 

Bm the currently latest version of Code Warrior (CW-5.3) docs not do it with 
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in lining scl in Smart "mid bnmdio 103 ^-instruction function when SingkTligO is 
called. I have replaced such instunccs with *ddine macros to get inlining 

Assumptions 


Frogmans (Lc. a word, of a sequence of non-word dutadmi) should Ik 1 less than 
64K characters in length. Hits is pretty well guaranteed in icxi files 

Input text characters are limited to the range DxUO to itxTF indusive 
Characters above UxTF will give incorrect results 
V 

find tide <stdUb,h> 

|include (string.h> 
include (ctype.h) 

#include “ToxtCompression.h rt 
#include "Ftaap,h H 
line 1 ude “tl 1111 r i on . h " 

Qjmpttssor Code ...."’ 7 / 

// 

. . .■ ■■ ■m , .m. , V / 

p.xxern Tables gTables: 

count 3 

kTokenSize - 14. 

kKax Dn i qu eToken ’ I ( K kTo k ft rtS I % e * 

// - max (liflcient tokens m a single block 

kHashBits -11, 
kHexHashTable - K<kHashBits, 

KHanhMank - kHaxHashTable-1 

U 


struct CKC 

// Standard CKl Ixised Ittslt method Good hashing at some expense in zim 

static struct CRC I 

enmn I POLYHOHIAL"Ox04clidb7i l: 
along tnb1o[2 r jfi] * 

CMCO 

( 

long I,j.x: 
for (i-0;i<2b6;i++) I 
x=K<24; 

for (5“0:i<8;f++) I 

If Ex<0) x=Cx«i) A POLYNOMIAL; 
else x T= (x«l); 

I 

table[i]«x; 

I 

J 

ulong HnshFunctionfuehar* tifr&.int FrgLcu) 
t 

// Uses ( :it<: on length and up to the first 4 chars of a fragment 

uluiig accuirOi 

aceurtHuei * fable [(accms»24> ft FrgLenJ: 

accmn=taeetmi«8) A table[£aeeun»24) A ufrg[0| |: 

if (frgLen)l) switch IfrgLen) 

default: 

eaae 4: accum~{ sccutn<<8) * tabic[Caecum)>24) A ufrg[l]]: 

case 1: neeuB^(8Ccurn«B) tablet Uceum>>24) A ufrgUjj: 

case 2: aceuia=(aruiini<C8J table [ Uccum> >24) A utrglljj: 

I 

// at urns 24 bits of l lie CRC + B hits form the fragment length 

return (accum & QxFFFFFF) | (frglen <C 24); 

1 

I crc: 


struct Token 


// bach Token describes u unique fragment of text 
// which occurs frvq times in a block 
if Fragments alien tile as words .md links, each with a 
// different character set of 64 elms. 

struct Token I 

Token* next : // linked list 

union 1 

uiong code; if cottehiis ai LSB,code length at S MSB 

uiong hashVaiue: 


The SlOW connection on this 


QuickPort™ wallplate is more than 
150 times faster than your modem. 


Want the right infrastructure for 
tomorrow's Information and enter¬ 
tainment technologies? Invest in a 
Leviton Structured Media " system 
today. Our Xtreme* jack can move 
over 100 floppy disks worth of data 
every second at speeds nearly 
20,000 times fasLer than the fastest 
modems, while QuickPorl optical 
fiber connectors deliver glga-speed 
access to the future. No matter 
where technology takes you, your 
Leviton Structured Media system 
will always look at home in your 
home, iL’s part of Leviton’s Decora 
system, the design standard for 
architectural-quality control and 
wiring devices. 



^integrated 

Levrior? Structured Media" systems 
am just one of fbe tfrovHtibfis m 
tatq^Bted Sofotions lor System 
Destriers. Hot more information 
or (he compete resource on CD WM, 
contact Leviton Integrator} Solutions 
at (80018770190 extension 789l 
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Unflffm*) A Connected WerM 


Why would V0I16 want a power 
outlet that looks like this? 

Because it's a lot better than seeing « 

red after an unexpected power line 
surge turns your computer or 
home theater system Into an 
expensive pile of junk. This Leviton 
Surge-Protected outlet is designed 
for applications where power 
quality is mission-critical. Why plug 
your home office or home theater 
into anything less? Especially when 
this professional-grade protection 
is also a genuine part of Leviton 
Decora, the design standard for 
architectural-quality control and 
wiring devices (yes, it's available in 
white and ivory along wilh fire- 
engine red). 
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^integrated 



Leviton SutgePrateded outlets are just 
one of foe formations in Integrated 
Solutions for System Defers, 

For more unfemratioo or fif>e compdefe 
, resource on CDfiOM. contact 
Levitor? Jnce^^atecf SoAJtnpns ar 
(800) 877-0190 extension 789. 


Q 1H99 Lfldlon ManufociunnG Co. H tnc. * www.levlTon com 
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h 

uchar* [tag; //fragmon 
ushorc fragLength: 

ushgrt freq; // number of limes in block. 

// set to 0 .liter code is published 

TokenOU 

Token(uchar* frg.int frgLen.int n) : 
ftagtfrg)» 
f ragLengtbdrgLen) * 
freqfn]. 
next(0), 
code CO), 

hashVahict(ftg)?crc.RashPunctionffrg,ftgLen);0) 


void EsfitFrequency (iftt x) {f req“x ;| 

if ini CodcLengthOitttum code » 27;} 

^define CodeLongfhf] code » It 

ulong MlnMsichtuchar* frg,int frgLen.ultmg bvalue} 

ulemg d - hvalue A hashValue: 

if id — 0) 

I 

uchar’ fl*frg; 
uchar* f2"frag; 
d"*fl * * f2; 

if (d — 0) for tint i-l:i<frgLen;i++) 

d El ++fi A *++f2; 
if (d) break; 

I 

I 

return d: 

J 

h 

Lypedef Token* TokenPtr; 


struct Token Node 

// A Token Nude is used in bidding the Huffman tree of tokens 

static long gMaxieugth; 
struct TokenNode 
I 

Token* t: 
int weight: 

TokenNode* parent; // 

TokenNndo* ehi Id[2J■//subtrees 

TokenModeC) 1J 

TokenNode(Token* token) : 

t(token).weight(r->freq)* parent(0) 

( 

child fOl "child! I 1**0; 


ToknnNgdefTakenNode & chi.TokenNode h c!t2j ; 
t(0). 

weight(chi.weight t eh2.weight), 
parent(0) 
i 

child fOj-firehI;chl.puresu = this: 
chi 1d J1}"&ch2;ch2.parent-this; 


int FteqO I return weight;! 

void Traverse(along code,int length) 

ff lluilds die Huffman codes for each leaf child recursive!v. 

I 

if ((child [0] bb !childL1J)//leal 

I 

if (length^O) lengths; 
t>code-code | (length<<27); 
if (gHaxLength < length) gMaxLength * length: 
I else 
t 

asuen (child [0] bb ehildtll); 


child[0] ->Trnversje(codfl<<l,length + l); 
child(1) >Traverse((code<<l) \ 1.lengthU); 
delete child [0]; 
delete child[IJ; 



typedef TokenHcde* TokenNodeFlr; 


struct Hash Bucket 

struct UashBucket f 
Token* first; 

Token* last; 

]; 


struct Token Set 

//TokcnSet holds all tokens of one kind (word or link) 

Struct TokenSet f 

int fill; // number of tokens defined 

int multi; // number of tokens used multiple limes 

int toaxFragLen; // longest fragment encountered 

int fra gLenSize:// nn mber of bits to represent longest frag length 

int cod eLen Size; // number of Inis to represent longest code 

int i iu in Cod e s : //n umber of 11 uffman axles dell ned 

// the maximum number of uniqtEC tokens, and the hash table size 
H arc defined statically to some reasonable values 
Token tokerJkMaxUniqueTnken]: 

HashBucket hsshTablcfkMaaHashTable]: 

Tokensct(): 

fi11( 2 ), multi(0).maxF ragLen(0),fragLenSize(0), 
cudeLetiSize(Q) 

I 

token tO j “Token (0.0. J ' ; // single txturrencc flag 
token [ 1 “Taken (0,0, 7):// multiple occunftncc flag 
memset(haEhTahle.0,si^cn : (hushTable)); 

I 

Token* Cache {lichar* frg.int frgLen) 

// finds the fragment in the cache, and increments its frequency 
ff If fragment b not found, a new token is defined and cached 
! 

int haEh=rrc!,finniiFuuciion(frg*±rgLen); 

HashBucknt* UB^&hashTableIkHashMask b hash]: 

Token* t=UB->first; 
while ft) 

I 

if (0 = t->HisMarch(frg*frgLen.hash)) 

if (t->freq — l) 
mulr i-H-; 
t->froq++; 

return t:// found cached token 

i 

t=t->next: 

1 

// add a new token to the ea< he 

if [fUKkMnxUniqueToken-l) 

I 

i f (ft gLen>maxFragLen) ntaxFragUn^frghrn; 
token ifil11“Token(frg.frgLen.I): 
t^&token[flllf+]: 

if (HB-Hast) 

I 

HR >last >next=t; 

J else iiB->f irst“t : 

I 

return t;// could be 0! 

I 

//The first two token spaces am reserved lor the flags 
// Token' SingleFbg() (return &token|0|l 
// Token* MultiFiagO [return Jfctokcnl I ];j 

#define SingleFlagO C&tokenfO]} 

#define HtiltiFlagt) f&token [ I!) 
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Programming Doesn't Have 
To Be This Difficult. It's REALbasic! 




^ - REALbasic is the award-winning, visual, 

object-oriented BASIC development 
environment for the Macintosh. 

Use REAtbasics visual interface builder 
and platform-independent language to build 
native, compiled—not interpreted—profes¬ 
sional quality applications in a fraction of the 
time it would take in C/C++. Because our Ian- 
guage is platform-independent you only need to write a single 
set of code to create applications for both Macintosh and 
Windows, Leverage your C/C++ experience to extend 
RFALbasic’s capabilities using shared libraries, Mac OS 
Toolbox and Win32 API calls or by writing cross-platform 
REALbasic plug-ins. 

Create prototypes, Internet applications, front-ends to 


databases, even games with REALbasic! its OOP language 
employs everything you'd expect from a modem development 
environment—methods, properties, classes, subclassing, 
inheritance, constructors and destructors, virtual methods, 
and more. The IDE supports multi-threading, extensibility, 
TCP/IP controls, plus multimedia and QuickTime tools, 
and support for standards such as SQL, ODBC, AppleScript 
and XCMDs. You can even import Visual Basic forms 
and modules. 

Go to www.realbasic.cotn NOW to download a 
FREE trial version or call 512.263.1233. 



REALbasic 

REALbasat is a registered trademark of REAL Software, Inc, 



MacPower 

Products of Thfe Year 


#*#* i 



Nlmrld 

t m 




New Product 


Mac Fan 


'Free update tor all owners of 
REALbasic 2 0 and abtwe 
All other trademarks property of 
their respective owners. 


Come see us at MacWorld New York — Booth #1970 







void HakeTokunCodes() 

// Pushes all relevant tokens on .1 priority queue, ifloieratts 

// the Huffman tree, ami then traverses it to assign each token a code, 

I 

Finish 0; 

// collect multi-use tokens on heap 

HeapCTokenNodcPtr* iiu> qmap (3+tnulti) : 

Token* t“token; 
for (iru i”0;i<fill:i++,t ++)1 
if (t->freq > 1} 
qiaap- Insert (new TokenNode (t)); 

) 

numCodes^qinap.heupfSJ ze; 

// build the Huffman tree for link codes 
while(qmap.heapSlze > I) 

( 

TokenNodePtr cbI“qinap.Pop£); 

TokersNodePtr chl^map.PopO: 

TokenNodePtr parent=now TokcnNudef*chl,*chZ): 
qraap, Insert (parent) : 
i 

TokcuNode* root=qmap F Pop(}; 

gMaxLengthH3; 

root ->Traverse(0,0); 

codeLenSizff=BftsNceded{gMaxLength); 

delete root; 

) 

void Finish!) 

// I JjKUtcs flag tokens with their frequencies ami calculates die number 
// of bits needed to send the fragment length when sending fragment* 
// explicitly. The longest actually occurring fragment determines this. 

1 

int fO“fLll multi; 

if U0<2) f0“2; 

token[0].SetFrequency(fO); 

int fl-multl: 

if (flO) fW; 

token (11. St? t Frequcncy (£1); 

f ragLnnS 1 ze~ftl tsNccded (raiixFragLeii): 


void SendFa rss (SitPump & B) 

// Sends the compressed text header, defining all constants needed 
// Ivy die expander before decoding can begin 

( 

B* Send (f mgbcnS 1 bg. b); 

B.ScndfcodeLenSize.b); 

Lnt numCode s 5 i 2 it s Need ed(numCodes]; 

B,Send{numCodesSize.5): 

B,Send(numCodes.nunCndenSIzp); 

B.Send(token!Q].CodeLpngth 0.codcLenSizc): 

B.Send(token[0]«rnde,t oken[0].GodELength()); 
B t Send(tokt>nt I! .CftdetangLht) ,eodeLenSize): 

B,Send(t oken[I].code * token[if,CodeLength()): 


void Send(Token 1 t,BitPump & B) 

// Sends a single token, either 

// just the token code (2nd or later ixcurrcncc) 

// "SingleHag” and a single fragment which will not recur 
// " M 0 It i Flag” ft vllt)wed hy a fragment and its 1< >kci 1 u xle 

I 

if U Hreq=0) 

( 

LL Send(t-)code,I -bGodeLengthf)); 

I else if (t’>ftBq=U 

I 

B.Send(SingteFlag() >code.SingieFlagO - >CodeLengtli()); 
B.Cottqi ressFragmeni ((uchar*) t->t rag, 
l > f ragLongth, f ragLenSize); 

1 else 

t 

B r Send(MuItiFJagO )coric*HulLlFlag() >CodeLength()); 

B. Compress Fragment (( ocha r 1 ) t > f rag. 

t->fragLength,fragLenSize); 

B.Send(t >CodeLe»jgth(),codeLenSize); 

B,Send(t >eode,t >CodeLength()); 

// SCI fnq-(l so this token will trigger code-only from ihjw on 


t->freq=0; 

I 

I 

h 


NextLink 

// Next Link and MextWtird parse the next link or word respectively 
// from the input text and return the length of the fragment. 

inline int NextLink(uchar' fnTcxl■uchar" endTexti 
I 

uchar* wordStart“LuTexc: 
while £ {1 JiTex t < e nd Tex t) & & 

tgTables.1sWordChar(*inText)) inText H; 
return inText-vordStart; 

1 


Next Word 

inline ini NextWord(uchar^ inText t uchar* endText) 

I 

ueliar * wordStart-inText: 
while ((inText<endText) Lh 

gTabies.lsWordChar £*inText)) irtToxi++; 
return inText - wordSta rt.; 


Compress 

static uchar* Compress(uchar 'text.long length, 
uchar* contpressedText,long b cowpressediength) 

// Compreffies a hkvck of text, until we either mn out of text to compresN, 

// unique quote space (fraglimit. allocated as a function of text size), 

// or die number of unique tokens required exceeds the static limit. 

// In the unlikely case we do run out. we return the compressed hkx'k 
// anti caller will call Compress :tgain to compress the remaining text 
uchar* ptext-text: 
ucha r * textEnd=text*1 rnigth: 

TokenSet * 1inkTokons-rmw TokenSet; 

Tok^nR^t* wordTokcns=new TckenSet; 

Ini csLNumQLtotePalrs = iength/5; 

im fragLimit=2 *cstNuJnQuotePairf)T 128 j 

TokenFtr* quotes=nev TokcnFtr[fragUmit+l 1 : 

TokenPtr* q=quotes; 

// Text might start ^ sili a worel or a link fragment : 

bool 1tnfaKirst=gTables,lsLink€har(*text): 

Int rrogFair=0: 

// si an text and gather all tokens 

if UinkFirsi) 

I 

int fragLengr.h=HextU nit Eptext. texiKnd J; 

•q-M—1 infeTokcnu >Cache(ptext .fragLength); 
p t ex t +“f ragLen gth: 


while (fpfexiCtextEnd)i&(fragFairCfragLimi11J 
int fragLength^KextWord (pt ext T IcxtEtid) : 
Token * 

token^vordTokeua >Cache(ptext.fragLength): 
If (0—token) 
hreuk; 
f q++=token; 

it ((ptextf»fragLeugth) >“ text End 3 

break; 

f raghengl h=tJex 1 Li ok (p t ext, text End); 

loke n“iinkTokens->Cac he(ptext,fragl^ngfh); 
if (0=token) 
break: 

*q+4=token; 
ptext+=f raging til; 

f ragPair++; 


int mnnQuotes“q-quutert; 
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// Make ilu- codes 


bool link: 


linkTok^mr-)HakeTokenCodes(); 
vordTokens - >MakeTc>kenCodes(); 

// Send alt quotes... 

q”quotes; 

TokenPtr" findQuotefi^uotCG+TiunsQuoLeH: 

// using a bit pump 

Bit Pump B( (uehur* )eoiiipressedText t 0); 

// send the header of a few parameters 

B.Send(1inkFirat,1); 

itit iinjaQuotesSize^BitsNeededt numQijntGs); 
B.Send(mjtoQu0tetiSizg,5); 

B, Send (numQurrtr.fi * numQuotes$lze ) : 

1 fnkTokens >$endPams(B): 
wordTokens >SendFeirmg [B); 

// scan the quotes may widi will alternate between word and link tokens 

if (linkFirat) 

{ 

Taken* t“*q++; 

assert Ct); 

11nkTokens >Send(t,B); 

I 

while (q<endQuotes) 

I 

Taken* t = *q++; 
assert(t); 

wordTokens >Send(t ,b}: 

if (q)-endQuotes) 
break; 

f*q+4; 
assert U); 

linkTokens->Send(t*B): 


ucbar * endOutText-B * Clone(); 
compressedLengtWndQutText comprosaedTcxL; 

// Clean up expUctrdy allocated memory 

//Automatic objects (Heap, ItttPump) will automatically dcstruct 

delete If quotes: 
delete wordTokenn: 
delete linkToketvs: 

return ptext: 

I 


Expander Code. . ...// 

// 



struct Node 

struct Nod e I // Node in decode tree 

long ftugLength; // fragLengih=tl for non-terminal nodes 
uchar* frag: // frag=0 for FLAG nodes 

Node* childL2]: 

h 


struct Expander 

struct Expander I 
iut fragLenSi 2 e: 
int codeLenSize: 
int nuraCodesSixe: 
lot nuraCodes: 
int flagOnlze; 
int flagOcode: 
int flaglsize: 
int flag!code: 
int numNodes; 

Node* node: 

Node* nextNode: 

Node* endNndp; 

Jnr nmnGuotesRcvd; 


// Constructor parses compressed file header Do establish needed 
// parameters anti define the bootstrap nodes of the Huffman tree 

Expander(BitPump h E.boof ink) : 
f ragLenSize(B.Receive(5)), 
codeLenSize(B T Receive(5j). 
numCodesSize(B.Recelve(5)j, 
numCodes{B.Receive(numCodesSIzc)), 
flagOsize(B.Recelvc(eadeLenSize)!. 
flagOtode[R.ReceivedflugOsize))* 
flaglsize(S.Receive(codeLenSize)) t 
flagleode[IL Receive(fisglsize)), 
numNades{2*numCodes j 1). 
node(new Node(numNodeel)* 
nextNode(node) r 
endNode (node-1 mitaNaden), 
numQuotesRcvd(0) T 
link[Ink) 

\ 

memset(node.0.numNades * sizeof(Node)): 
nextNade=node+l; 

HakeNodetflagOsize.flagOcode.O.))://single flag 

KakeNode(flaglsiz« t flagl code ,0 ( 2}:// mufti flag 


-Expander0 I delete [] node:I 

void MakeNodefint size,along code,uchar* frag,int 
fragLength) 

//Traces from mot to the node define by the axle, assigning missing 
// intermediate nodes as needed. 

// Installs fragment length ant! text pointer in the leaf node 

Node* n=node: 

int bit; 

far (int i=size-l;i>0;—i) 

t 

bit=1 h [coda >> 11: 
i f (0—n >child[bit]) 

[ 

assert(nextNode < endNode): 
n->child[bit]=nextNode++: 

I 

ti“n*>child [bit]; 

I 

bii“l h code: 

assert(nextNode < endNode); 

Node* terminaiNode^nextNode f+; 
assert (0=n '>child [bit]); 
n->chiId[bitI=terminalNode: 
tenninalNode - >f ragkength** f ragl ^engl h i 
terminalNode->frag=f rug; 


itit CetLinkQuof e (Bit Pump & B,uchar* dest) 

// Parses one link quote I mm the compressed text 
// returns tile number of expanded characters decoded 

f 

int bit=B .Receive £ I); 

Node* n®node >chiId[hil]; 
lot Fraglength; 
for (::) 

I 

int xfiag^n->fragLongth: 
if (xflag) 

l 

uchar* frag~n >fr.ig; 

If (frag)// cached qttote 
I 

fragLength^xflag: 

*dest“*frag; 

while (-xflag) *++dost ^ *++ftag; 
break: 

J else // new quote 

I 

f rafilength^B. Receive (f ragLetiSize); 
B.ExpandLink(dest.fragLengt.h): 
if (xflag=l) //SinglcFTig 
break; 
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// else Multi Flag: ruche the code 

I n i cud eLengt h=B * Hec e i ve {cod eLetiSi z e); 
iril eode=fl. Receive (codeLength); 

MakeNode (codeLength*code. dest* f ragLength); 
break: 

t 

I else 

I 

bi t=B ,Rorr i vc l H H 0 ;// trace path in ircc. hit by hit 
n”n > c h_11 d [ bi LI ; 
assert(a); 

I 

I 

return fragLength: 

I 

.int GutttordQuote(BitPump & B*uchar* dest) 

// Parses one word quote from the compressed text. 

// returns ihc number of expanded characters dccrxled 

I 

Int bit-B'Receive(3); 

Node* n=node->chlld fhUl ; 
int fragLength; 
for {;;) 

I 

int xf1ag=n->tragicngth; 
if (xflag) 

uchar* frag"n Ofrng; 

if (frag)// cached tjtuMe 

I 

f ragLcngth=xflag; 

1 dest** frag; 

while (^xflag) 'ifdest ” *++frag; 
break; 

f else //newquote 

frngLength=B,Receive[fragLenSize); 
fl-ExpandWord{dest,fragLength); 
i f C xf 1 a g^= l) // SinglcFlag 
break; 

// else Mu Id Flag cache the code 

I nt rodcLcngth^B.Receive{codeLenSize}; 
int code“B.Receive(codeLength): 

MakeNode(eodeLength. code T dest,fragLength}: 
break; 

1 

1 else 

i 

b i r^fl. R nc e i v e 1 H i L: :// mice path in tret, bit by hit 

n^n >chlld[bit)r 

assort(n ); 

l 

I 

return fragLength: 

1: 

Expand 

static udiar* Expand( 

uclmr* cmtipressedText. long compressedLength. 

^ uebar* expandedText* long & expandedLenglh) 

// Creaks expanders for both word am] link fragments, 

// reads the compressed text header fields, anti expands the text 

BJrPump 

(ucha r *)compressedText* 

(udiut * 1 JcoffipressedText+cotnpressedLength): 
bool linkFirst^B.Reccive(l): 
int nuuiUuotesSise^B.Receiveh); 
int nuiaQuotes=B.RfircivetmiJtiOuotcsSixe): 

Expander 11nkCocfos(B *true): 

Expander wordCodeslB*false); 
tic ha r 4 eiexl=expandedText : 

// starting u itli either a link ur a word fragment,^et alternating 
// link and word quotes from the hit pump, decode into plain text. 

// and place results into the cxparHletflbxt army, 

if (HnkFirst) 

I 


Int T ragLongth-iinkCodes *GetLinkQuote (B ,etext); 
etext +- fragLengtb; 
nmQuotes—; 

I 

while fnumQuotes) 

I 

int fragLength=wyrdCodes,GetWordQuote(B»etext); 
etext -H- fragLengtb; 
numQuutes-; 
if [numQuotes^^O) 
break; 

f r a gLength 13 J i n kCod ex -GctLi nkQuo te(B,etext); 
etext += fraghengLh: 
man Quotes ; 

I 

expandedLength - etext expandedText; 

// return the state of the compressed text pointer, in case 
// die whole text was not compressed as a single Mock 

return 8.Buffer!); 

I 


. . External Functions *™*™™«*«***'*y/ 

// 

/ /. . . i f 


IniifJompresskm 

void 4 r yourSmmge 7 I tdtCompression(void) 

// No persistent storage needed 

return 0; 

I 

CompitssText 

long r expressed length */ Coin press Text f 

char 4 tnpuiTexi* /* text to be compressed V 

long rural nputChars. f length of LnputText in hytes V 

char * comp ressedText, /* rcium compressedText here */ 

const void "yourStorage P steerage returned by InitComprcssion V 

fpragms unused(you rS1orage) 

urhflr* lt=(udiar 1 )lnputText; 
u e bar 1 * c t=(uc ha r *}comp res sed Text: 

1 ong 1 i t=munl npu t Cha rs.lct; 

1 otig compressedLength^O: 

// t su.tUyJexl slkiuld compress in x single Hock. 

// Just in case it dcx*s not, this loop will etimpifss text in W*xLs 

do 

I 

uehar' LZ^orapressUt.lit.ct.lct); 
eonip res sed Length let; 

lit = t2 - it: 
it - t2: 
ct +* let; 

1 while (litHi); 

return compressedLength: 


ExparrdText 

lonj f* expandedLcngth 7 ExpanrfTexi ( 

char 4 compressed Text, P cnc^xled le\l to he expanded 7 

1 on ? comprennndT^ugth, f length i>f encixkd text in bytes 7 

e ha r * ex pa r \ d cdTex L. t Ttturn ex panded text here 7 

on ; '/old ‘yourStorage P storage returned by InitOmipression 7 

^pragma unused(yourStorage) 

ucha r * ct=(uehar*)comp r en n cdToxl; 
ucha r * e t-( nc ha r *)expond edTex i ; 
long lcfcoi«pressedLengtfa,let: 

1 ong expaudedLength^O; 

// I suaffy. texi should conte as a single arm pressed hhxk 
//Just in ease it dtxrs not, tills loop wilt expand multiple blocks 

do 

I 

uchar’ t2=Expand(ct* let*cl.let); 
expanded length +=■ let: 
let = l 2 - ct; 
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ct * t2: 
et t= let; 

) wh U p {let > 0): 

return oxparidetfl-ongrh: 


if (x^O) return 1; 
int n“0: 

do I x »“ 1; n++-1 whUe{x) ; 
return n: 


Term Compression 

void TermCompressionC 

void *yourStorage f storage rauimifbv luitCompression 7 

) i 

tfpruguui unused(yourStorage) 

// No persistent storage to <kstmv 

\ 


Utilities.h 

flifndef UTIUTIES_B 
Idefine UTILITIES.!] 

fdcfihe WDEBUG 
flticludc <assert.b> 

typedef unsigned duu uebar: 
typedef uchsr* uchart 1 tr; 
typedef unsigned short ushort; 
typedef unsigned long along; 


inline ini Caps(uebar* vl.uchar* v2) 

// returns tnic if capitalization of wl and wi differs. 

1 

return ((‘wl * *v2) & 0x20); 

I 

inline int BitnNeeded(along x] 

// returns number of bits needed u> encode range 0 io x 


class Tables t 
public: 

TablesU; 

bool IsWordCbar(uebar c )I return textehars(c]:J 
bool IsLinkCIhar (uthur e) I return ! textehars [c]: I 

urhnr Ascil2Code(uebar c) I return af:cii2code[cl: f 
urha r Code2Unk(uchar c ) I return coded1 i nk [cl; I 
ucluir Cod e2Almim( uebar cjtreturn code23lmim[r] ; \ 
prlvnLo: 

bool l cm chars [2561 : 

Uc ha r a scillcode ( ?. r i 6]; 
uchar code2link[64]; 
uchar code2ainuini64] ; 


class bit Pump I 
public: 

Bltptmp£uchar* text.Lcbrar* end): 
buffer(text). 
endBufforfend). 
acc(O), 
fUUO) 

II 

void Send(along x, int nunBits) 
t 

acc «* numbits: 

acc x & (U«numBits) 1); 

fill I “ftumBits: 

while (fill >= 3) 

t 
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fill ■= a: 

•buffer** = (acc » fill) & QxFF: 

J 

I 

ulong Receivetint munMtii) 

I 

while (fill < nuasBlis) 
t 

tf (buffer>=endBuffer) return -3; 
ace ** (acc«8} | ■bufferH-; 
fi 11+^8: 

I 

fill *= mnnBits: 

ulong x = (acc>>fill) 6 (tl<<!iumBits) 1) ; 
return x; 


ulong KecoivclBit() 

I 

if f!till) 

I 

if (buffer>-endBuffer) return I; 
acc = (ace<<S) | *buffer++: 

I 

fill 

return (acc»fill) b 1; 


void CompressFragmeriiCuchar* irag.int lengLU,ini mimfiits): 
uc.har* ExpandLinkfuchar* outText,int length): 
uchar* F.xpandWord(uchar• mitText*int length): 
uchar 1 Buffer()I return buffer;! 
uchar* Closed; 

private; 

ulong Receive6Bits(); 
uchar* buffer; 
uchar* endBuffer; 
ulong acc: 

long fill; 


); 

ffenriif //IJTHJTIES.H 

Utilities.CP 

# I net tide <rfype«h> 
ffincludt "Ul 31 tt.teru'h" 


Utilities Implementation 7/ 

// 

...—. 7 / 


Tables gTables: 

Tablet::Tables0 
I 

Int rnmAlmm^D; 

for {int c C5 Q;c<128:c++) 

! 

if Elgalnum(e)) 
l 

textnharsfcl = true; 
uunAlnum+t; 

I else textchars[e] “ false: 

1 

If (!textehars [ J) \texteharsf '#*]*ti:ue:nu»AlnuiirH-; 1 
if f! t ext char sb .*]) Itextchars['_‘ Jennie;tmaiAlmtin++; I 
assart (numAlruim — 64):, 

int almuuCodo^OJ InkCode^O; 
for (int c“0;c<128;e < t+) 

* 

if (texteharsLcJ) 

t 

c ode2 ulmm f al nutnCod e 1 -c: 
use i 3 2code f c ] ^alnuaiCodet-t: 

] else 

I 

Code 2 linkLiinkCode]=c; 
ascii2code |cj ^litikCode-H-; 
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* 

textchar128+c] 37 textebars (c]; 
asci l2c©de[lZB+c) - ascIi2code[c3: 


for (int i=0:i<length;i11) 

t 

*outText i i 31 

gTabIei:_Code2AlniMi!(Kt>ceive6Bits (, I ;// xlatc la ASCII 


inline ulong BitPuinp: iRpccI vebBitsQ 

// return -111 jf buffer empty 


return outText; 


if (fill < 6) 

I 

if {buffer>“endBuffer) return -l; 
arc = (acc<<8) | ’buffer►h 
fill+^B; 

I 

fill — 6: 

return (aoc>>fI11) & 63; 


void fli t lump:: CotnpressFragment {uchar* frag.ini length,int 
numb its) 

I 

uchar* s a frag-I; 

Send(length,nuraRi t r>} \ 
for (int i-0;t<length:i++) 

\ 

lnl c-*++a; 

Send { gTables. Ascii2£ode (r} * ft):// xLitc ASCII to 6 

1 

1 

uchar' BitFump:iRxpandLink(uchar* outText.int length) 
far (Int 1=0:i<length:i*+) 

*outText+t * 

gTab les .CodeZLink (Rece i vcbfil ts t j ;// xhue lo ASCII 

( 

return ourText; 

I 

uchar* BitFump: : Expand Word (uchar* outText.int length) 


THE PRODUCTS YOU NEED. WITH THE 
PRICES AND SERVICE YOU DESERVE. 



WWW.DEYDEPOT.COM 



PG Quit SIQQ * WMMk Village, CA 9U59-52&Q * Voice: SWWMACDEV-1 (800/622-3381) 
Outside USCanada; 805/494-9797 * Fax: &0S/494-979B * E-mail: ordered*vdtp6t.com 


uchar' BitFump;:Close () 

I 

if (fill) 

Send (0. 7 k £ 3 1 nil)) *// zero pad last by le 
return buffer; 


Heap.h 

lifndef HEAPJf 
fdefine HEAFJ1 

template (class Base.class Value) 

// Note class Base must 3 kt a pointer to a etas 
// luiving a member FreqO of type Value 
// Value must have the operator > defined 

struct Heap I 
Base* heapRase; 

Ini heapSize: 
int maxHeapSIze; 

Heap(Int size) : 

heapBssetnew Rasefslxe+I]). 
heapSize(Q), 
ffiaxHeapSi ?.e(s kc) (| 

"Heap () I Clear {); I 

void Clear()I deleteLJ he&pBase;! 

void InitUnt size)! 

beapBase=new Base fsize!1]; 
heapSize=0: 
maxHeapSize=s1ze; 

1 

void Insert(Rase k) 

I 

int i^+heapSize: 

Value wk~k->Freq(): 
int j=i»l; 

Base z; 

while (j (wk < (z=heapBase(j))->Freq())) 

beapHaseliJ=z; 

i=ji 
j=i»i: 

1 

heapBase[iI“k: 

I 

Rase Pop() 

I 

//the node ai heapBasel 11 b the lowest weight 
//it is amoved from the hop .ind returned 
//the heap is readjusted 

Base r c=hea p fta se[I ]; 

Base k-heapHase [beapSize-J ; 
if (heaps!ze<=lj [ 
heapBase LlJ“k: 
return rc; 

J 

int i“i,j=2; 

Value vk=k->PreqO; 
while (j<“hoapSize) 

if t(j<heap5ize) 

64 (heapBasel j] ->Fr&qU > beapRasel j+I) >FruqO)) 

j++; 

if (heapBase[j] >Frcq[) > wk) 
break: 

heapHose[±]=beapEase l j j ; 
i=j;j+=j; 

I 

heapBase LiJ-k: 
return rc: 

\ 

k 


hmi I f 
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MAC OS X 


By Andrew C. Stone 


Adding AppleScript Support to Cocoa Apps 


The divide between user and 
programmer is effectively bridged with 
AppleScript - Apple's scripting language 
wiLh a natural language syntax. 
Providing a developer's API for your 
application is nice, but far more people 
will be able to use AppleScript to 
interact programmatically with your 
application. ScriptEditnr, the Apple 
program which executes AppleScript* 
ships with OS X in /System/Applications 
and is available in BlueBox for OS X 
Server in the AppleExtras folder. 

The gofxl news is that it's very easy to 
add AppleScript support to Cocoa apps, 
especially if you followed my advice last 
month and designed your application in 
three separate pieces: the data model, the 
view, and the controller. Because 
AppleScript talks directly to the data 
model, most of your work is already done. 
Cocoa's AppleScript implementation 
makes use of the key-value coding that 
you already have in place, and it "knows " 
what methods to call to gel and set 
instance variables of your objects. 

This article will explore the basics and 
then propose a mechanism to add 
automatic applescript generation to your 
application so users can see the script 
necessary to create any given document* 
Wei! extend the Sketch application which 
is provided as source code in 
/Systom/Devetoper/Examples/AppKit/Sketch. 
Copy that folder to your home directory so 
you can modify it as we go along* 


The Basics 

There is a complete introduction to AppleScripting In Cocoa tn 
/System/Documentation/Devetoper/YellowBox/TasksAndConcepts/Progr 
ammingToptcsyScripting/ScriptableApps on OS X Server and 
/System/Documentation/Developer/Cocoa/TasksAndConcepts/Program 
minglopics/Scripting/ScriptableApps on Developer Preview 3 of Mac 
OS X, This is a valuable introduction, but don't get bogged down 
in the derails! What you need to know depends on how far you 
want Lo take it, so let s look at it from a top-down perspective; 

There are three major components to your AppleScript 
implementation; the Script Suite definition, the Script 
Terminology, and any additional code required to implement 
special commands or special accessor methods. The Script Suite 
is a property list which defines the mapping between apple 
event codes, classes in your app, and the exposed instance 
variables of those classes, as well as handled commands. The 
Script Terminology is a localized property list which defines the 
mapping between your class names and attributes and the actual 
English for French, German, etc) terms used in AppleScript to 
communicate with the objects in your data model. Terminology 
lets AppleScript know what are valid syntactical constructs. 

One of your major resources in defining your suite and 
terminology is the NSCoreSuite and NSTextSuite which Apple has 
provided. They will serve as an invaluable resource on how lo 
write your own suites and terminologies, Your app gets free 
access to all of this functionality, especially if you have utilized 
the Document Based Application architecture available as a 
project type in Project Builder. You might want to drag these four 
files out onto you desktop for easy access and reference: 

NSCoreSuite: 

/System/Library/Frameworks/Scripting,framework/Resources/MSCor 
eSuite.scriptSuite 

/xSystem/T.lbrg ry/FrameworkEi/Srr [ pt i ng. f rioncwork/RenourreFT/Engl i 
sh*lproj/NSCoreSuite,scriptTerminology 

NSTextSuite; 

/Systeifi/Library/Frameworks/AppKitSeri piIng.Iramcwork/Rcsourccs 
/NSTextSuite.scriptSuite 

/System/Library/Frameworks/AppKltScripting.framework/Resources 
/English.lproj/NSTextSuite * flcriptlenainology 


Andrew Stone <andrew@stone*com> is the chief executive haquer at Stone Design Corp <http://www.srone,com/> and 
divides his time between raising children, llamas, & cane and writing applications for Mac OS X, 
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To use scripting in your application, you will need to add 
the two frameworks, AppKitScriptmgiramework and 
ScriptingTramework to your project in Project Builder. 

Home, Suite, Home 

The Suite definition has 5 top level components; the name 
of the suite, the Apple Event Code for the application, its classes, 
its commands, and any synonyms. Each class defines its 
superclass, attributes, to one and to many relationships, and the 
ubiquitous 4 letter Apple Event Code. These Apple Event Codes 
need to be unique, and Apple has reserved all lowercase 
combinations (26 * 26 * 26 * 26 or almost a half million 
possibilities) for themselves, so it behooves developers to throw 
in at least one uppercase letter in your codes. The code is used 
to map attributes and relationships behind the scenes of the 
AppleScript implementation, and is used as a hash key to 
quickly retrieve information from the AppleScript dictionaries. 

A skeleton, do-nothing, suite would have the following 
entries; 

i 

"Maine" ” H GrpovyAppSuite*; 

M AppIeEventCode , ‘ = "GASt”; 

"Classes" = I 

h 

"Commands" “ [ 

k 

"Synonyms" = ( 

k 

You expose your model by defining the classes which arc 
part of your data model. In the case of Sketch, the 
DrawDocument, Application, Graphic and its subclasses are 
exposed. The Sketch dam model is quite simple: a document us 
a (ist of graphics. A real life drawing application, such as Stone 
Design's Create, would have a grander, recursive definition; A 
Create document is a list of pages, each with a list of graphics, 
which contain either simple graphics or graphics which are 
groups which contain a list of graphics (which contain either 
simple graphics or graphics which are groups..,). 

Describing a class involves up u> 6 components: its 
superclass, the Apple Event Code, the attributes, the one to many 
relationships, the one to one relationships, and the supported 
commands. Only the Superclass and AppIeEventCcxle fields are 
mandatory, as for example, the Rectangle Graphic subclass: 

"Rectangle” = [ 

“Silperclass" ” "Graphic"; 

*App1eEv em L Cod e" ~ " d 2 r c "; 

1: 

Attributes 

The attribute section is where you expose the instance 
variables of your custom subclass by defining its type and its 
unique Apple Event Code. The Cocoa AppleScript framework 
will use key-value coding to automatically generate the glue 
code to allow a user, for example, to set the color of a rectangle. 
Because a subclass of Graphic inherits all of the attributes of 
Graphic, RccLanglc will also have the fill color attribute: 


‘Attributes" ** \ 

/* expose you: ivars here - no code needed if you have 
methods named: 

setXXXX: and XXXX */ 

"fillColor" - ( 

"Type" = "MSCol or": 

"ApplelventCode" = "fclrk 


The scripting framework will look for a method named 
“setEillColor:(NSColor kcolor” when attempting to execute the 
simple applescript a)de: 

sot tlio fill color of graphic 1 to "red" 

In Sketch’s Terminology, the mapping Ixiween the instance 
method “fillColor” and “fill color” arc made: 

"fill Color" = | 

"Name" = "fill color"; 

“Description" = “The fill color."; 

Part of the magic of Cocoa AppleScripcing is the automatic 
coercion of values to appropriate data types, in this erase, the 
string “red* to a valid NSColor object. There are several ways to 
express colors in AppleScript: 

1. You am describe the color by its name, such as “black”, “blue” 

2. You can pass a string containing three space separated floats 
between 0.0 and 1,0 expressing the red, green and blue 
components, exp: "0.5 03333 0.7777" 

3. (Post DP3) You can pass an array of three numbers between 
0 and 2*16 -1 (65*535)* Arrays are expressed with braces in 
AppleScript, and items are comma separated; for example: I 
25000, 888 t 65000 I 

Attributes that take a boolean, integer or float should be 
assigned the type "NSNumber” coercion will be made to the 
appropriate scalar type. 

Let s expand Graphic by exposing the boolean values that 
control whether a graphic’s stroke or fi!! is drawn, the 
“drawsStrokck and “drawsFilf methods. Add the bold lines to 
Sketch. scriptSuite: 

"Graphic" * i 

"Superclass" = "NSCoreSuite, Abstractor ject": 
"AppleEventCode" & "grph"; 

"Attributes" = ( 

“drawsStroke” = [ 

"Type" = "NSNumber": 

“AppleEventCode* ~ "sDrS"; 

u 

"drawEPill" = I 

"Type" * "NSNuraber"; 

"AppleEventCode* = "sDrF*; 

k 

Now, add these terms to Sketch,scriptTermlnology so we 
can set and get these values; 

"Graphic" = I 

"Name" — "graphic": 

"FluralName" - "graphics": 

“Description" - “A graphic. This abstract class 
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reprsfi^iUG ihe individual shapes in a Sketch document . There 
are aubclasses for each specific type of graphic. 

“Attributes'* * [ 

"drawsStroke" = I 

“Nasie* = “stroked*; 

“Description* - “Is object stroked?*: 
h 

"draw$Mll" = I 

"Nanie” = “filled": 

"Description* - “Is object filled?*; 
h 

Non-solar object values are also valid. You need to expose 
the class that is being passed as an argument, arid assign the 
“Type" to this class. One important “gotcha" Ls that the attribute 
which takes this object must have a unique Apple Event Code 
different from the object s class. This is not the case of the 
"Type* field in One to one and One to many relationships, where 
the Apple Event Code must tse Lite same as as the class code. 

One to Many and One to One Relationships 

One to Many relationships allow you to expose lists of 
hems; which are at the core of any data model. Even if you are 
using dictionaries, you can expose them as One to Many 
relationships. Sketch's NSDocument subclass, DrawDocumcnt, 
exposes two types of lists: the actual set of graphics in a 
document, and subset lists of each type of graphic:: 

"DrawDoeument* - I 

“Superclass* = "KSCoreSuite.KSOocitiftent"; 

“AppleEventCode" " "docu"; 

“ToManyRelfiti nnahipfl" - f 
“graphics* * I 


“Type" - "Graphic"; 

“AppleKventCode" 11 "grph": 
h 

"rectangles* * { 

"Type” “ "Rectangle": 

“AppleEventCode* * "d2rc"; 

h 

Again, it’s very important to note that the Apple Event Code 
for lists have the exact same code as in the Class definition, for 
example, a Rectangles Class code is u d2rc": 

"Rectangle* “ l 

"Superclass" = “Graphic": 

"AppleEvantCode" * "d2rc": 

1; 

Besides the usual accessor methods expected by 
AppleScript, such as setGraphics: and graphics, to many 
relationships alsc^ expect a way to insert an object at any point 
into the list, based on Lhe pattern: 

-{void) inRertTnmX:(<mX type) ManXXXOfaject 
atlndnx: (Int) vbcreToJnsert 

So, for example, with graphics, you would implement an 
additional method beyond your normal accessors for use by 
script driven insertion; 

- {vo I d) t nuer L iiiGraphlcs: (Graphic *) graphicToAdd 
atIndex:(intJvhereTo Insert : 

Good object oriented design practice would probably have 
you implement this in terms of a the primitive "setGraphics;”. In 
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ease back pointers or other setup is required, you will not have 
duplicate axle since you “factored* this new method: 

- (void) insertluGraph lcs : (Graphic 4 ) graphitToAdd 
atlndex:(intlwherefoinser l f 

NSMutableArray 'a = [NSMutablcArray 
a e rayWithArray:graphics] ; 

[a insett Object:-graphic at Index: whereToinsert] ; 

[self setGraphics:a] ; // call the primitive irunhod 


Additionally, you can also implement these methods for use 
by scripting: 

- {void)addlnGraphi.es: (Graphic ■}graphic; 

[void)renoveFromGraphicsAtIndex: {unsigned)index; 
(void)replaceTnGraphics:{Graphic ')graphic 
at index:(unsigned)index: 


See Mike Ferris's implementations of these on line 305 of 
DruwDocu roent. in in Sketch. 

On OS X Server L2 and Developer Preview 3, tliere Ls a 
mild limitation which will go away for OS X premier: you cannot 
tell a generic' Graphic to set an attribute of a subclass, even if 
that graphic is of the subclass type. Class coercion is coming, but 
as of this writing, this won't work: 


make new image at before graphic 1 with properties (x 
position^ y, position:!), width: 100, height: 100] — add 
a new image 
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set the imagefile of graphic 1 to 7Some/Cool/lmage.tifF' 


Instead, the second Hne of apple script needs u> be: 


set the image ft le of image 1 to "/Some/Cool/1 lramge.1 iff’ 


This is a fairly contrived example because you could have 
passed in the "imagefile” argument to the properties array, but 
Lhis explains why the non-existent subset arrays are exposed in 
DrawDocumenfs "ToMtanyRelationships": rectangles, images, 
circles, lines, and text Areas. Basically, Sketch just grabs those 
graphics which are of the desired class and returns an array with 
that subset: 

// so Scripting can talk to the images in the document 

(NSArray *)images l 

return [self graphicsWlthClass:[Image class]]; 

1 

// run through our list of graphics and build n list of the subtypes 
// on the fly: 

{NSArray ’)graphicsWithClass:{Class)theClass [ 

NSArray graphics = [self graphics]; 

NSttutableArray 4 result = fRSMutableArray array]: 
unsigned i* c = (graphics count]; 
id curGraphic: 

for fi=0; l<c: i++) [ 

curGraphic = [graphics ob jectAt'Index: i]; 
if ([curGraphic iEKindOfCiass:theCiassj) ! 

[result addObject:curGraphie]; 

I 

I 

return result; 

] 


The NSTextSuite is available for use by Cocoa developers 
for simple scripting of the Text Object: setting font size, font and 
color of text. It has a good example of a ToOneRdaLioaShip: the 
mapping of an NSTextStorage to texf: 

"NSTextStorage w = I 

"ToOneRelationShips" = I 
"text" “ 1 

“Type" - "NSTextStorage”: 

"AppleEvetitCDde” - "ctxf*: 

U 

1; 

This cyclical definition allows you to "setText” and gel the 
“text” of an NSTextStorage object, the core data model behind 
every NSTcxtView. Since the Cocoa Text system is designed 
using the Model-View-Q>ntmller pattern, it lends itself to 
script ability. You can also see examples of the use of synonyms 
in l he Text Suite and Terminology, 

Commander Coding 

So far, weve taken advantage of key-value coding and 
haven't had to add much code. We can create and modify 
graphics, but in order to add more functionality, we need to add 
more commands. Since 1 noticed the “open” command was noi 
working as of tills writing, lets create a new command, 
“openfile” to open an existing Sketch document. There are 4 
steps in adding a command: defining the command and its 
arguments in your Suite, defining which classes support the 
command, creating a terminology for the command, and actually 
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wriling the method which glues the NSScriptCornmund and your 
preexisting axle to accomplish commands, 

[n designing a command, think first of how a user might call 
it, For example, it would lx i natural Lo say: 

tell application ^Sketch 44 - note that on DP3 you need to say 
"Sketch,app" 

openfile at "/Lncul/Users/andreiif/SketchSainpXe,sketch” 
end tell 

Step Is To the bottom of the Sketch.scriptSuite add a 
Commands section: 

“Commands’* - I 

“OpenFile“ ® 1 

“CorawridClass* “ "NSScriptCommand*; 

“Type” = "NSObjectReference 4 '; 

"ResultAppleEventCode" *= “obj 

"Arguments" = ( 

"FileName* - I 

“Type 1 * w "NSString”: 

“AppleEvencCode" = “oFNe"; 
h 

h 

"AppleEventClassCode 4 * = “s 1 ctc M : 

“AppieEventCode" ® “opFi": 

I: 

1; 

Because this command takes one string argument, the file 
name, we have to define die file name in the “Arguments" 
section of the command. Commands can lx 1 of the generic 
NSScripcCommand class, or they can lie NSScriptCommand 
subclasses that you create for special handling purposes You 
need to define the return type of your command in the 
"ResultAppleRvemCode" field. The Apple Event Code M obj 4 can 
be used to return an object, anti the "'Type" field would be an 
"NSObjeet Reference*. If you don’t want to return anything (a 
void method), use this- 

“Type” * 

Note thar the “Applet:ventClassCode” is die same as our 
Suite Definition s Apple Event Code. The Apple Event Code for 
every command should, once again, be unique. 

Step 2: Define the class or classes which supjxm the 
command. In this case, just the Application knows how to open 
a file: 

"NSAppiication” = i 

"Superclass* ” "NSCoteSuite.^Application" : 

"SupportedCoHcmaiida” = f 

“Sketch,OpenFlie” “ "handleOpenFileCoironand:*; 

1; 

h 

Nf>ie that we designate die "OpenFilo command to be 
handled by the method named ^handleOpenFdcCommand:" 
which takes a single argument, the NSScriptCommand. Well add 
that method to a new source file “Scripting_Additiom,m n that 
will contain all of the extra code we add to Sketch, 

Step 3: Map the command and its arguments to your 
native language. In English. Iproj/Sketch.terminology, add 
this at the bottom-. 


SPOTLIGHT 
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Find memory errors automatically in source 
Code Fragment Support a 

Leak Detection U 

Toolbox Parameter Checking Jjgj 


“Commands" “ ( 

"OpenFile" = I 

“Name" = “openfile”: 

"Description" ~ "open a file": 

"Arguments" - t 
"FileName" - I 
“Name" = "at"; 

"Description” **■ “The file to open should follow, quoted": 

): 

I: 

Is 

U 

Step 4: Write the method handleOpenHleO>mmand: 

Add a new source file to “Other Sources" suitcase In 
Project Builder, Script ing^Ad ditioas. ni, Well use the powerful 
“Categories' 1 mechanism of Objective C which lets you add to 
and override methods of existing classes. The override part is 
tricky though - if more than one category of a class has an 
alternate implementation of a method, it is indeterminate which 
method will get called. So use categories with care! 

Since NSApplitation handles the “OpenFile* command, we 
implement a category of NSAppiication: 

me r f a c o NSAppllcation (S c ript ing_Add it ions) 

lid) hand leDpenFiieComiiisnd: (NSSeriptCoimsnd * I command i 

// ask the command lo evaluate ils arguments 

^Dictionary *args = [command evaluiiiedAcgiiinentsJ ; 

NSStrisg *file - [args objeetForKey:# H FileName*]; 

// If we don't have a file argument we re doomed! 

if (I file j| [file isEqualToString:#”"!3 return [NSNurabcr 
tiutnberWithBool :NOj t 

// ask ihc Application delegate m do the work: 
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return jKSMumber numberWithBool:[tseii delegate] 
appllcation:self openFile:file] j ; 

\ 

Send 

Note how tlie script command knows how to evaluate itself 
and its aigumenrs, and we just have to check the dictionary for 
the file name via the key " File Name", same as in the Arguments 
section of the command definition. 

To take advantage of more object oriented (OO) magic, 
namely the ability for an application to open files dragged on the 
application tile or via services, well implement 
applicatiomopenKUe: in a DrawAppDelegaLe category. And 
using the Cocoa Document Based Architecture, it's as simple as 
asking the shared NSDocumentController to actually do the 
work: 

#imp 1 ementation DrawAppDelegaie{Sc ripting^Addi Lions) 

(BOQL)appl1 cat ion;{NSApplicatiort *)sender openFile:(NSString 
1 )filename I 

id doc = 11MSDocuaentController sharedDofimentController] 
openDocuraentVithContentsOfFile:fileuarae rilsplay:YES|: 
return (dac 1= nil) ? ¥ES: WG; 

J 

§cnd 

Teach Yglfr Users Wf.tj, 

Having your application be scriptable is one thing, teaching 
your users how lo write scripts is another. So lets add a feature 
to Sketch which I originally implemented for Stone Ovate, the 
ability to save any document as an AppleScript that can then be 
executed in ScriptHditor to reproduce that document on the fly 
via scripting! This is useful for creating complicated templates 
which get modified slightly to produce current content. 

Hie Object Me Kiel has many benefits, including code 
reduction, reusability, readability, modularity, data hiding, and 
data indqxmlcnecc So we'll take an OO approach to the design 
of our Script writer, with this simple algorithm to output the script: 

make a new document 
for each graphic do 

ask the graphic to make a new graphic just like itself 

By creating a mutable string, each, graphic will lie asked in turn 
to supply the Apple Sc ript needed to recreate it. Then, since an 
NSString knows how to save itself to disk, we’re basically done. 

Graphic will do must of the work, but will allow overrides and 
hooks for subclasses to set their special attributes, 
additionsIPmpcrties lets you specify any attributes to set during 
creation, such as the file name of an image, in whether a line goes 
up or down, setHxtraPropertiesIntoStringtkToreTcil and 
setExtraProperties tnt<xString lets you set attribute's of the object after 
its creation, such as setting font and color attributes of a text object 

I've modified Image to “remember” its source file by adding an 
instance variable _sourceHleName t and modifying imagcFile lo 
return this, as well as Graphic View to set the image file name when 
you drag one in. Caveat: if you "paste* in a graphic, it won t have 
a filename, and thus won’t lie able to reproduce itself via a script. 


Step X: Add a new menu item to the main Menu: 

a. open I)raw2.nib in tnterfaceBuilder 

b, Drag a menu item fn>m the Palette to the File menu 

c title it “Save As AppleScript,..", command-key: 

<OI y riONxA> 

d Double-click the First Responder in the “Instances* pane 

of the DrawZjlib window 

e. Double-click the “Actions" icon to drop down the actions 

f. Type <RfcTUttN> to add a new anion 

g. Rctitle “myAction:" to “save As AppleScript Action:” 

h. Control drag l>etween the new- menu item and the First 

Responder icon 

i. Double-Hick “saveAsAppIcScri ptAelion:" in NSMenultem 

target inspector 

j. Save tile nib. 

Step 2: 

Well continue adding axle to Scripting^Additions.m, starting 
with the top level method s; i ve As AppleScri pi Action:. Since each 
df xrnnent needs to know how to do this, the method will Ise 
implemented in a UrawDoaiment category, Tlie metli<xJ will 
provide a Save Panel to allow the user to specify the script name, 
start the object graph writing the script, save the script, and then 
message the Finder to o]x-n the newly saved script for testing in 
Script Editor on OS X and in Edit on OS X Server (where you can 
copy/paste it into BlueBoxs ScriplEdilor). Because we want our 
Cocoa applications lo he fully local izable, well use the 
NSbxiili/edStringFnjmTahlc-O niacrt > sc > that kxnJizers can me Kiify 
the axle to work without changing any source axle. 

Moreover, since we want the ende to work on X Server as well 
as X, well use -ilclef SERVER w here special code is needed for OS 
X Server. For example, X Server uses newlines \n’ to delineate lines, 
but Mac OS X and Script Editor use a carriage return, Ar\ 

Since there Lire some bugs in Q xx >a scripting in Developer 
Preview 3, well I use another test lor ^ilclef DF3- To compile on OS 
X Server, add “-DSKRVFK into the Compiler Flags field in the Project 
Inspector's Build Attributes window. Acid “d)[)]\T if you are 
compiling on Developer Preview 3 

Finally, for a Cinrbon apploiion, such as ScriptEditor, to 
recognize and open a script file, we need to set the IYPH and 
CREATOR of the file. Thai will lx- accomplished wiili the help of 
some axle I got from Ken Oise of vvwAV.Omnignxip.com with a 
friendly NSString interface I added. 

Tin: Code 

// Siripiinft_AiMiikiitt.li 

#Import <AppKlt/AppKi! >h> 

// import <Scriptinft/Scr I pi lng,h> 

//import “DrewAppDelogaty .tr 
//import '"DocutoentHodei .subproj/Ut^wUoetitQGfitnr 
//1 mport "DocumentModel. svbproj /Graphic. h" 
tf i mport “nocunentjfccbl, subproj / Lino ,h* 

//import “ Hoc ament Hod e I. niihproj /Circle ,h" 

//Import “ilocumon i Mod e 1 . niihproj /1 mafte.h" 

//import M DocuiuttniModel, :>ubpro]/Text Area, h* 

^interface NSAppiicatlon(Scripting.jAdditionn) 

(id)hsnd 1 eOpenFileCommand:(NSScriptCoraraand *)command; 


80 


Aimjinc, AppleScript Support to Cocoa Aim’s 


MacTech • July 2000 









Owned and Managed by 

«IDG 

WORLD EXPO 

Flagship Sponsor 


Ahead of the times for over 15 years. 
MACWORLD Conference & Expo has 
been the only arena where: 

© Industry leaders, Mac professionals, 
and all levels of Mac users gather to 
discuss the latest products, services 
and solutions for the Mac Community 

One-stop Shopping! 

© Featuring 400+ exhibiting companies! 


Conference and 
Workshop Programs 

IliHr 18 - 21,2000 


Exposition 

inly 19 - 21.2000 


Begister by bibs is, wm 


® Awards and competitions! 


© Hands-on demonstrations! 


© Prizes, drawings, and giveaways! 


Cuttiog-edge 
Educational Sessions! 


© MACWORLD Conference & Expo 
is a comprehensive event 
featuring interactive workshops, 
the MACWORLD Users 
and MACWORLO/Pro Conference 
programs, the Keynote address 
and other special presentations 


Macworld MacBuyfcom KacCentral.com MactNEEK.com MOCUlQrld.GQfll 















©end 

#Inter face UrawAppDelegate(Scripting_Additions) 

// tliiv is a gsxid method Lo add 

// it allows Skcldi Ui open documents via tile service interface 
■ (BOOL)applicat ion: (NSApplication T )sender 
openFile:(NSString *)filename: 

©end 


AppleScript".©"Sketch",©"Save panel title when saving a 
document as a script”) 

^define CmiW_$AVE_$CRl PT NSLocalizedStringFromTahie(@”CouXd 
not save Apple Script to %#, Check file 
permissions. Sketch"*#"Save panel title when saving a 
document as a script”) 

ffdefine OK NSLocalizedStringFromTable(©*GK". ©"Sketch".©"yen 
ok") 


©interface OrawUocument(Scripting_Additions) 

// the ukiIkxI you lux* up the menu item to the First Responder hi Drawlnib: 

- (IBAction)saveAsAppieSc tiptAction:(id)sender; 

// lift 1 actio! method which generates the AppleScript: 

- (NSString *]app1eSrript: 


(TBArtf on)saveAsAppleScriptAction:(id)sender I 
Static NSSavePanel *aavePanel = nil; 
lifridef SERVER 

NSWindow ‘window - [[[self windowControllers] 
objectAtIndex:Oj window]; 
lendif 


//TYPE/CEEAIDR: 

(int)setTypeString:(NSString *)type 
andCreatorString:(NSString 4 )crestor ForPath:[NSString 
*)path: 

©end 

©interface Or a phi c(Scripti ng Add, i t ions) 

// each graphic knows it's own appk script: 

- (void)appleScriptlntoSt ring:(NSMutableSt ring *)s: 


//gel and keep a save panel setting it’s name to a localized title: 

If (IsavePanel) [ 

saveFanel = [[NSSaveFanel savePanelj retain]; 

[savePanel setTitle:APFLE_SCRiPT_TITLE] ; 

1 

// give the lik; u g<xxl default name based nn the document’s filename: 

if ([aavePanel runModalForDirectory:©"" file: [[[self 
fileName] 

s t r 1 n gBy Lie 1 et ingFat liExte n s ion J st r i n gBy Ap p end ingFat hEx tens ion:© 
"script"] 


// EACH (GRAPHIC Ml 1ST OVFRRiDK THIS WITH ftS OassName feci Terminology' 

- (NS String *)app1eS c ripiName; 

// EACH GRAPHIC MAY OVERRIDE IIJLNR 


(void) setExtraPropertiesIntoStringBeforeTel 1: (NSMu i ab 1 cS 1 r \ rig 
*)s: 

(void)RetExtraPropertiesTntoString: (NSMul ableString * )s: 

- (NSString *)flddItionalPrnperLies: 


// of course, wc want to use Sheers since they am swxtt lxxjII 

lifndef SERVER 


lendiF 


r e1a U veToWind ow:window 


]) ( 

NSString ‘file - [saveFanel filename]: 

//do the work of collecting tlx 1 appIcScripi in a .simple method: "appldscript" 

if (![[self appleScript] writeToFile:file 
atomically: YES 1) 


©end 

// tripling, AddjtkMiK.m 

litnport *Seripting_Additions,h" 

// for flixkTTTPE/CREA'niR magic: 

^include <unistd,h> 
linclude <sys/types,h> 

//include <sys/stat*h> 

//include <sys/attr^h> 
linciude <fcntl.h> 

©i®p1emcnta Lion NSApplica tion(Scripting_Additions) 

(id)handleOpenFileCommand:(NSScriptCommand *}command [ 

// ask the command to evaluate its arguments 

NSDictionary ‘args - [command evaliiaTedArgumcnifs] : 
NSString ‘file = [args objectForKey:@“FiIcNarne"]: 

// ii we thin t have a file argi imt-n:, we n- doomed! 

if (If tic || [file isEqualTuString:©""]) return [NSNumber 
numberWllhBool:NO]: 

// ask die Application delegate lo do the work: 

return LNSNumber numberWithBool:[[self delegate] 
application:self openFile:file] 1 : 

I 

©end 

@ 1 mp lemon tat ion DravAppDe legate (Script ing^Addit ions) 

(BOOL)application:(NSAppiicatidn *)sender 
openFile:(NSString *)filename I 

id doc = [ fNSBoeuwwtCamtroller shartvdDocumeruCont roller] 
openQoc.umenTWIrhContentsOfFflc: filoname display:YES]; 

return (doc I* nil) 7 YES: NO: 

I 


// something went wrong: norifv 
#ifdef SERVER 

NSKunCriticalAlertFanel(APPLE. SCRIPT TITLE f COULDNT SAVE^SCRIPT 

*OK,NULL.NULL,file): 

lelse 

NSRunCr i LicalAI er t PanelRe 1 at i ve To Window (APPLETS CRI PT_T ITLE. COU 
Li»NT„SAVE_SURlPT.OK,NUU.NULL,window,file); 
lendif 

// So qxm ii uji - bin provide a way to turn off dlls lielm'kmr a default: 

else if {![[NSUserDefaults 

standardUserDefaultsI boolForKey:#"nontOpnnAppleScript"l) ( 

// some OMNI magic: 

[seir 8etTypeStrlfig:0"TEXT* 

andCreatorString:©"ToyS" forPath:flie]; 

// try to open it up with the new sellings of StriplRIilor 
// the aliennk owe is witii a space between Sc ript and Editor 

if (If[NSWorkspace shsredWorknpace] openFile;file 
lifndef SERVER 

withApplication:©"Sc r tprEdIvor" 
lend J F 

] &6r ![[NSWorkspace sharedWorkspace] openFiie:file 
lifndef SERVER 

withApplication:@"Script Editor" 


* 

I 

// Ixtc well be Abk: to kxalize our Apple Script that we pnxlixc 
//we need to use newlines in Server, and carriage returns tin X 

lifrief SERVER 


©end 

©implementation DrawUocument (Scripting^Additiottit) 

Idefitie APPI .E_SCR T PT_TT TL,E NSLocali zed St ringFromTab 1 e(©" S ave 


Idcfine ‘i'ELL_APF NSLDcalizadStringFroinTabie{@"teil 
application \"%©\"\n".©"Sketch”,©^AppleScript tell app 
statement") 

//define TELL DOC NSLocallzedSrringFromTnb1c(©" tell the 
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front document\rT 1 @"Sketch n .©"AppleScript tell dor 
statement”) 

define N£W_LK)C_SCRIFT WSI.ciraHzedStrinRFrociiTable{« H make 
new document at before front 

document \n m Sketch” ^"AppleScr i pt create new doc phrase") 
^define COMMENTEDjreW_DOC_SCR IPX 

NSLoca1IxedStringFromTablef©"- broken In DPI uncomment next 
line to iecti\n— make new document at before front 
document Xu"Sketch”,fl“AppleScript create new doc phrase”) 

//define END__TELL NSLoca 1 izedSl r mg ?romTahle (©" end 
tell\n H .8”Sketch”.©”AppleScript end toll statement") 

flelee 

//define TELluAPP NSLoealizedStringFromTablef^tell 
application .©"Sketch" .^“AppleScript tell flpp 

statement”) 

//define TELL_D0C NSLocalizedStringKromTabletell the 
front document\r”, ©"Sketch". ©"AppleScript tell doc 
star einent”) 

^define NEWJ)OC_SCRTPT NSLocalixedStringFromTabie make 

new document at before front 

docuraentVr".^"Sketch” t §"AppleScr3pt create new doc phrase”) 
//define COMMENTEO_NEW_DOC_SCK1RT 

Mf>T*QC3HzedStringFr0mTabie(@"- broken in DP3 uncomment next 
line to test:\r— make new document at before front 
documentor".©"Sketch",©"AppleScript create new doc phrase”) 

//define ENUJTELL. N Shoe a J UedStringFromTable(#"end 
teller".#"Sketch".©"AppleScript end tell statement") 

tfendif 

fdefine TMAG_FTLE NSLoca lizedStringFromTable («r , 
imageFile;\"%@\”" t @ H Sketch"! ©"Applescript extra stuff for 
image") 

//define LINE_£TUFF NSLoeidiftedSl r IngFromTablef©", goes 
Up:toT Sketch", ^"Appiescript extra stuff for line") 

(NSString *)appleScript [ 

NSMulablcString # s - [NSKutsbleString 
stringWitbCapacity:AOOO]; 


unsigned i = f g raphic a count): 

#ifndef DP3 

NSString 'appName = ©"Sketch": 

//el pe 

NSString *appName m ©"Sketch,app"; 

//end if 

[s apptmdString;[NSSrring 
s t r ingWithFo mat: TKLL APP. a p pNatue 1 ] : 

/Zifndef DP3 

Es appends t ring :NEW_DOC_SCmPTj : 

#else 

(s appendst ring;COMMENTED NEW DOC_SCRIPT|; 

//end it 

\s appends t ring MELl^pOC] ; 
while (i- > 0) f 

Graphic *g = \ graphics abjectAtlndex:i]; 

[g oppleScriprIntoString:sJ; 

1 

[s appetidSt ring \ 1 " ] : // make tile "cud Idi" nested in j bd 
U append St ring ;ENUJXEU.3 ; 
fs appendString:ENDjrELL] : 
return s; 

l 

typedef Struct \ 
long type; 
long creator; 
short flags: 
short locationV: 
short location!!: 
short fldr; 
short iconID: 
short unused[3]; 
char script; 
char xFiags; 
short comment; 
long putAway: 

] OFFInderlnfo; 

(int) set Type: (unsigned long) typeCode andCreator: (unsigned 
long) crestorCodo forPath:(NSString *)path; 

I 

tfifndef SERVER 

struct attrlist attributeList: 
struct I 



Introducing... 


_ version J 

Funnel 

Web 


Funnel Web s innovative design and 
powerful feature set helps make sense 
ol complex Web sites by identifying 
key trends and events. 

Features 

* point and click interface 

• over 50 reports and graphs 

• up to 50 times faster than 
major competitors 

• platform independent 

* works with any web server 
on the planet 

Advanced Technology 

• Event Messaging 

* Remote Administration 

* Realtime Monitoring 


Intelligent Web Monitoring and Analysis 


Accuracy, speed, ease of use and powerful report-formatting 
capabilities, makes Funnel Web the perfect solution for 
monitoring e-commerce. Intranet and Internet sites. 

Backed by Active Concepts unrivalled 24 hour technical support. 


Download a free demo version at 
http://www.activeconcepts.com 

or visit our website to find out more 
about the killer Funnel Web Spider,... 







long ssize: 

OFFinderInfo finderInfo: 

1 aUrlbutefiuffer; 
ini errorCode: 

NSFileHsnager *fm - fltSFileHaiiagor do fault Manager J; 

a tt ribuieLl r*r *bJ tmapcounL - ATTK_BITJtAP_CQONT; 
attribut el*i sr.reserved - 0; 
attributed 1st*CQM 0 Ci& 4 ttr = ATTRCMN FNDRINF0; 
artributeLisuvolattr “ attributelist«dlrattr - 
attrihntel. 1st.fileattr = attributeList.forkartr ” 0; 

mettSet UattributeBuffer* 0 * sizsof (at t rlbuteBuffar)); 

getattrlistEffm fileSysteroRopreBent^tionWitbPath;path!* 
kattributeList * ha11 ributeRuf f er * sizeof{atf tibuteBuffar) 

0); 

ittribut eBuEfer.finder Info*type - typeCode: 
all ribuieJiuiier. finder Info, creator - Croat or Code; 

errorCode - setettrliat(ffm 

fiieSyatemRepreseiitationVi thPath:peth], fcattributeList. 

&att ributeBiiffe r* f S nderTn To, sizeof(OFFinderlnfo), 0): 
if (errorCode — 0) 
return 0; 

iT (ermo = EOPNQTSUPP) I 
#define MAGIC JIFS^FILE LENGTH 82 
unsigned char 

magicHFSFIleConterirf; EMAGTCJiFS_FiL£_LENCTH| - ( 

0x00* 0x05* 0x1 b* 0x13 / * 0x00. 0x02* 0x00* 0x00* 
0x00. 0x00. 0x00* 0x00* OxOO* QxOQ* 0x00, 0x00. 

0x00* 0x00* 0x00. 0x00* 0x00. 0x00* 0x00. 0x00* 
0x00* 0x02* 0x00. 0x00* 0x00. 0x09* 0x00* 0x00, 

0x00. 0x32* 0x00* 0x00 * 0x00. 0x20. 0x00* 0x00. 
0x00* 0x02* 0x00, 0x00, 0x00. 0x52* 0x00* UxOO, 

0x00* 0x00* *L‘* *y', ‘p‘ ( 'e', *c*. 'r** 'e*. 
*a\ 0x00* 0x00* 0x00* 0x00, 0x00, 0x00* 

0x00* 0x0D, 0x00* 0x00, 0x00, 0x00, 0x00, 0x00* 
0x00* 0x00, 0x00, 0x00, OxOO. 0x00* 0x00* 0x00* 

0x00, 0x00J; 

unsigned int 6ffeetWht»ri0STypefiAreStoted = bO; 

NSData *data e 


vsustuir 

1-88-USB USB US 

-or- (1-888-728-7287) 

WorJdWide Distributors of VSB 
and FireWire Parts, 
Peripherals and Accessories 


Hey Developers: 

http; //WWW. usbstuf t .com/developer8.httnl 


1-877-4 HOTWIRe 

-or- 1-877-446-8947 


fireMUreStuff 


NSSuing 'nwgicHFSFilePath; 

* (Uni 

*) (kmagicKFSFileContents [offsetWhereOSTypcsAreStored])) « 
typeCode: 

" ([int ") (&magicHFSFi 1 pConr erity lof fsetWhereOSTypesAreStored 
+4])) - creatorCode; 

data ~ [NSDiua dataWithBytes :ciagicHFSFileCotitents 
length:KAGT CJTFS_F1LE^LENGTH); 

ma gic1 iFSFil ePa th = [[path 
ntringbyDeletingLa st PathCompo n en11 
sLringayAppendiiigPathCcmponent; f@" *_" 
strlngByAppend ir.gS t r Irvg: fpatb la f;lP at hCumponent] J J : 

t f {ffm crealcFIleA tFath: magicHFSFi1ePath 
contents:data at i ributes:iim fileAttributesAtPath:path 
traversedInk: NO]] ) 

return 0; 

else 

return errorCode; 

1 

return errorCode; 

if else 

return 1: 

If endlf 

I 

- (unsigned long)eodeFromString;(NSString UEourLet ter Word I 

unsigned const char *c - [fuurLetterWord cString]: 
if ([fourLetrerVord cStringLengrhJ — 4) I 

return ((c[0)«24) + (c[U«I6) + (t[2]C<8) t c[3l); 

1 

rcLurn 0; 

I 

- (int)setTypeString: (NSSt r trig M type 

andCreatorString;(NSString *)creator forPath:(NSString *)path 

return [self setType;[self cod©FromString:type) 

sndCreatot:{self codeFromStringrcreatoiI forPath;path]i 


@end 

// localize the Graphic strings: 

tflfdef SERVER 

Adel ine NEW_0BJ£CT NSUicaHzedSi ringFruraTable(# 1, \t\tmake new 
W at before graphic I wiih properties lx position;^* y 
positioned, width:Id. belght:%d* stroke color:%P* stroke 
thickness;*!* stroked:*d* fill color:%@* 
fillfMi:td\®j\n™*@"Sketcb’\@' , AppleSeript new Object.*) 

//define TELL_CRAFHIC NSLocalixedStrlnp,FromTabte{@*UUtell 
l\rf .ITSketch" ,@"AppleScript tell graphic slalcmeiil") 

//deline F0NT_SET NALncal 1 xciTSt ritigPmiiiTabie(@*\t\tset the 
font of W of I to \“%@\*\rr ,@ ft Sketch’' .^"'appl©script to 
set the font of a text area™) 

H efinc FONT_S1ZE_5ET NSLocalizedStringFromtahle(@ M \t\LseL 
Ihu sise of of 14® 1 to %d\n™ .^Sketch™,r'applescript to 
set the font of a text area") 

//define FONT C0LQR_SET NST.ocal ixcdSiringFroniTable(@*'\t\tset 
the color of *4^ of lt,@ I to %@Vn" .^"Sketch" ,®"appiescript to 
apt the font of a text area") 

Idefine SET.CHArCOLOR NSlocalized8trlngFromTable(@"\t\iseL 
the color of characters ltd through %d of of 1 to 
t@\n™*Sketch",®"applasertpr to ::ri the color of a range of 
characters of a text area") 


//define SET_CHAKJSIZE NSLocalizedStringFroaiTflbJe(@"\t\tsot 
the size of characters %& through of of W 1 to 
: 3.2f\n™.^Sketch",@™applescript to net ihc font size of a 
range of characters of a text area") 

//define SET CHAR_FGNT NSLocalizedStringFromTable[@*\t\taet 
the font of characters %d through %d of W of %@ 1 to 

Sketch" ,@™applescript to set the font of a range 
of characters of a text area") 
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#else 

//define WEW_OBJECT NSLocal I/edStringFroniTableC©” VtYtmuke now 
at before graphic 1 with properties lx positioned* y 
posit ion:%d. width:%d. height:%d, stroke color; %©* stroke 
thickness:%f, stroked:%d, fill color: *4©. 
tilled;%d%©]\r",©"Sketch”,0”AppleScript new Object”) 

fdefine TELLjCRAPUlC NSLoeaHzed S t r ingFromTabie(t"\t\11c 11 %» 
l\r" ,@”Sketch”,©"ApploSr r ipt tell graphic statement") 

//define FONT SET NSLoealizedStringFromTabie(®*\t\tset the 
root of W of W I to \ w %e\"\r"*#"SkGtch",» H applMcript to 
set the font of a text area") 

//define F0NTJ512ELSKT NSLoca 1 izedSt ringFroaffable (@”\ L \t set 
the size of W oi W f to ^dVr”,@"Sketch" .©"appleecr Ipi to 
set the font of a text area”) 

//define FONT COLQR.SET NSLocalUedSl ri ngFrnmTable (©" VtAtset 
the color of %9 of 1 to %@\r" .ff^Sketch" .©"applescript to 
set the font of a text area”) 

//define SSr_CJIAK_€OI-OR NSLotalizedStringFromTabU*(@”\t\ts pr 
the color of characters id through %d of of W 1 to 
%©\r 1 \#” Sketch" .©"applem !ipt to net the color of a range of 
characters of a text area") 

//define SRT_CMR SIZE NSLocalizedStringFromTnble(^ M \t\tset 
the size of characters Id through Id of of W I To 
%3,2f\r",©“Sketch”.©"applescript to set the font size of a 
range ot characters of a text area”) 

//define SETJCHAR.FONT NSLocal lxodStringfir«tfr«blete'’\t\ts^t 
the font of characters %d through %cl of %@ of 1© 1 to 
\”i@\“\r” 4 ®"Sketch“ ,@”applescript to set ihe font of a range 
of characters of a text area”) 

//end if 

//define TEXTJGONTKNT S NS Local IxedStringFt omTa b 1 e (©” * t ex L 
contents:\”%@\"”,©“Sketch” H ©”apple script to set the text ot a 
text area”) 

NS&lring ’appleScriptColor(NSColor 4 e) ! 
float i,g T b; 

1 [c colo r Us 1 ngCo 1 o r $paop.Name :HSCaiibratedRGB€olurSp3ce1 
getRed: &r green: £tg blue; kb a 1 pha: NULL]: 

return [NSString stringWIthForrast"%f u 4f %f\"". 
r *B*h]; 

I 

©implementation Graphic [Scripting_Additions) 

- (voitOappleSL-rlpLlntoSrring; (NSHutableString *)s t 



Web Server 4D 3.2 

http://www.mdg.com 


WS4D/eCommerce 
a single application 
that does it ail! 


Web Server 
Database Publisher 
eCommerce Server 
Handles Virtual Domains 
and all your Databases 


Hosting Services Now Available 

• WS4D & WS4D/eCommerce Hosting 

• Co-Locating {including 4D & 4D Server) 

• We are 4D & 4D Server experts and have 
been working with 4D since 1988. 

Database Hosting $50/month 
eCommerce $ 100/month 
Co-Locating $400/month 

To find out more about MDG Hosting, visit: 

http://mdg.com/hosting.htmi 


// EACH GRAPHIC MIGHT OVERRIDE THIS CORKfiCTiLY 

(void)setKxt rePropertiesItJtoStringBeIorcTo 11 :(NSHutableString 
•)s [ 

I 


- [voidlsetExtraFropertiesTfiToString: (NSMut ablest ring *)i» I 


I 

// for example: return contcmsA'tuV’ 

- (NSString MaddltionalPrcperties ( 
return g”; 

I 


fs appendString;[NSString 
st r i ngVithRortnat; NEWJQEJECT, [self 

appleSrriptNarae)*(int)(NSMinX(^bounds)).lint)(NSMinY(_bounds)) 

,(inL5(NSWidrM bounds)),(int)(NStfeight(_bownds)), 
appleScriptColor{ strokeColor) ..lineWldth, (iuL)_gflagr:.drawf:St 
roke. appleScriptColor { 11 iColor} * (int )_gFlags .dravuF HI* [fieri f 

additionalPrppert les] ] ]; 

[self setExtraFtopertieslriLaSLr 1 ngReforeTell;s] : 


©end 

©implementation Circle (Scripting_Extrns) 

- (NSString *JappleScriptNnme f 
return 

NELocalizedStrii]@FTomTable{S&”circie” .©"Sketch” ,©”App1.CGCri pt 
name of this object”): 

I 

©end 


[s appetidString:[NSString 

stringWit hForma t:TELL GRAPHIC,Iselt appleSeripiNamn]11: 

[self setExt raPropertIesIntoString:s]: 

[s appendStrina;©”\t\t.”]; 

[ s ap pe ndSt ring: END_TELL}; 

I 


// EAUI GRAPI UC MUST OVERRIDE TUTS CORRECTLY 

- [NSString *)appieScripiNtimo l 
return 

NSIx 3 ral1zedStringFramTableIf"ret tnngle",©"Sketch”,©”Appleec rip 
t uaffle of thin object"); 

) 


^impl^menintlon Image (Scripting^Extrae) 

- (NSString *)appleScriptName I 

return 

NSLocalizedStringFrouiTabli (©”1 wage”,©"Sketch”,@"ApplearrIp1 
name of this object”); 

] 

(NSString *)additionalProperties ( 
return [NSString 

fitringtfithFotniaL ;TNAG_FrLE, sourceFileNameJ ; 

i 

©end 

©implementation Line (Scripting^Exir ob) 

- [NSString *)appleScriptNanie I 

return 
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NSLy cal izedS t ringFromTab 1 e (#“ 1 ine*. ^Sketch". ©"Applese r i pr 
name at this ob-fect"}; 

I 

- (NSSt.Htig * )addiLionalFroperties | 
return {NSString 

fltr I ngWithFormat:LINE_STUFF. (int)_irrarisALLowet:LeftJ l 


Send 

^implementation Tex l Area (Script in ^Extras) 

- (NSString •)apple£criptNaine t 

roiiirn RSLocaiizedStringFromTabl o(<?**text 
area",fe>"Sketch*\@ ,l Appleficript name of this object"): 


' (NSString *] erica peSiring: {NSString *)inString [ 

NSMutablestring = [NSMutableString string]; 
unsigned 1, c * [inString length]; 
for (i - 0; i < c; i++) I 
unichar c: 

if CCc - [ inString cha raclerAtlndex:!]) = 4 “ 4 ) [ft 
append St rid g:#“\Vl ; 

[s append Format ;^%c".c] : 

I 

return s: 

* 

(NSString “) con tents Name j; 

return NSL&calizedStr IngFromTable (SFthe text 
contents"^"Sketch"^"Applescript name of what in In a 
text"): 

] 

// we need m escape any cmlxtldctl quotes; 

(MSString 0additionalProperties I 

*m [NSString nr r i ngW* lliFormat:Ti . ■?!TS* [self 

eecapeString; Unel f contents] string]]]; 


(BOOL)color:(NSColor *)color equals:(NSColor 1 )color2 

float r + g.b..ri,g2,ba; 

1 [color 

coiorUsingCo 1a r Spa reName; NSCa 1 ibratedRGBCo 1 orSparc j gelKedr&r 
greeting blue.'Ab a 1 pita;NULLJ: 

[[color? 

co \ o rUs 1 ligColorSpaceHame: NSCa li br a t edRGBCoIorSpace ] getRed: &r2 
greemig? blue;&b2 alpha:NULL]: 

return (r “ r2 U g “ g2 b “ b2); 


//a tixihodkui swiruh through tltc text ftir a I tribune 

// otHJld lie opnmi/nl by using cJTcclivc range, but this works fine 

- (NSFont “)font I 

NSText Storage 'contents = [self contents!; 
if ([contents length]) 

return [contents ati ributetNSFontAtlributeNamp 
at Index :0 effectiveRringciNULL]: 
else return nil: 


- (NSColor •)textCoiorl 
NSColor *c * nil: 

NSTextStorage 'contenta = [self contents]: 
it (|contents length]} c - [contents 
attribute:NSFnregroufuJColorAttributeName at Index :0 
effect! veRa nge: NU LL]; 

if (lc) c ” [NSColor blackColor]; 
return c: 


(void)searchStringForAllAttributes:(NSHutableString *)a I 
NSColor ’lastColor = [self textCoiorl: 

NSFont MafUFont « [self foot]; 
float lastSize - [lastFont pointSJze]: 

NSString MastFontName = [lastFont font Name j 

int length - [f[self contents] string] length]: 
int newColotBeganAt T rcdex * Q: 
int newSize&eganAt Index = 0: 


int newFontNameReganAtIndex “ 0: 
int curlndex: 

for (curIndex “ 0: curlndex < length: curlndex++) I 
BOOL IsLast — (curIndex ™ length I): 

NSDictionary *atts = [[self contents] 
aLttlbutesAtlndex:curIndex e f Tec LiveRange:NOLL]; 

NSFont “font = [aLLs 
ob j ectForKey: NSFont At t r i bu t eName] : 

NSColor 'color “ [atts 

Ob j ectFor Key :NSForeg round Colo rAt tribute Name ]: 

BOOL colorChanged; 

BOOL fontChanged; 

BOOL sizeUhanged: 

if (1color) color = [NSColor blackColor]; 
colorChanged “ ! [self color:iastColer equals:col or]; 

if (colorChanged j| (isLast)) I 
// rlic text bkx.k already Itts iljc correct enter of ihc first several chanicicrs... 

it (colorChanged && newCo 1 orBeganAtIndex H 0] t 
[s appends1 ring:[NSString 

sLringWithForraat :SET CHAR^Of.OR, uowColorBeganAtIndex + 1* 
curIndex,[self contentsName],[self 
appleScripr.Natne] . appl eSc riptColor (lastCol or) ] ]; 

newColorBeganAtIndex - curTndex; 

I 

if (isLast &A newColorBeganAtIndex !“ 0) I 
[s appendString:[NSString 

^lringWithFormat:SET CHAR_C01DR,nowColorBeganAtIndex + I, 
curlndex+l,[self contentsName].[self 
appleScriptName],appleScriptCoior(color)] I; 

newColorBeganAtIndex “ curIndex; 
lastColor =* color; 
i 

sizeChanged » ([fyisi pointSize] !- lastSize)?YES:N0; 
if (sixeChaneed jl (IsLast)) [ 

// the text hkxk iilrcsKiy lut* tk a j rati align of tlie first several dtirnctcrs. 

if (sizeChanged 4& m aAtIndex != 0) f 

Is appendSrHtig; [NSString 

isiringWifhFonnat;SET CHAR S^ZF, + nowSizeBeganAtIndex + l f 
cur index, [self content sName], [:self 
appl eScriptNatne], last Size] ] j 

newS i ze Be ganAt Index * cur Index: 

if (isLast newSlzeBeganAUndox != 0) 1 

[s appendStr1ngr[NSString 

SiringWithFormat :££T CHAR.ST7,K*fiewSizeBeganAtIndex + l. 
cur Index + l,[self content aNaitio], [uelf appleScriptName] * [font 
pointSize]]1: 

J 

nowSizeBeganAtlndex 3 eurlndex: 
iautSize - [font pointSize]; 

) 

font Changed = [[[font fomN^UDe] 
isEquaiToSt ring:lastFontName]; 

if (fontChangcd ]| EisLast)) ( 

// die text block iilrtady Ins the ccmxt iilign ol die first several characters,.. 

If [fontfihanged newFontNamoReganAlIndex 1= 0) 

[s appendst t tng;[NSString 

y LtingWithFormat:SET CHAR_FDNT.nr 1 wFuntNameBeganAtIndex f 1, 
curlndex* [self contentnNatne] . [self 
appieSc r iptName | T 1 as t Fon l Niitfie I); 

newFontNameRegaiiAi Index = cur Index; // needed ter nexr if statement 

I 

if (isLast newFon t Name Bo ganAtIndex 1= 0} I 

Is ap pendSt ring:[NSS t ri ng 

sitirigWithFormat:SET CHAR_,FONT.nowFontNameBeganAtIndex + 1, 
curindex + l,[self contentsName].[self appleScriptName], (font 
fontName]]]; 

! 

Fiewi'ontNameBe ganAt Index = curindex: 
lastFont Name * [font font Ha me] ; 

J 

* 

I 
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(VOid) se L Ex t ra P r o pe r tiesInt oSt r i ngBe £ o reTe 11: £ NKMutab leStr ing 

•)s I 

[s appendstring; [NSString stringWithFontwt:F0NT_SET* [self 
contentsName] f [self 41 ppT eScriptNamel . L [seif font] 
fantName]]]: 

[s appendString: iNSString 

Sirin gWi t hFormat : F0KT_SIZE_$KT, [self cnntentsNameL [self 
appteScrtpfNamel, (int)[ [sell foot] point Size] ] 1: 

[a appendString:[NSString 

etringWithFonnat:FOt^T C0L0R_SET. [self contentjsNamp] .[self 
appleScriptName] *appleScriptCol0r{[self textCulor]) ] ] ; 

[self gearchStringFor All Attribute's]: 

I 

#end 

Step 3: Add Hissing Instance Variable to Line subclass: 

Sketch * sc riptSuite: 

"Line* “ I 

"Superclass" = "Graphic"; 

"AppleEventGode" = "d2ln"r 
r andrew -> we rxrd to be ahte lo make lines go up anti down! 7 
"Attributes’* “ I 

" start sAlLowerLeft* = ( 

“Type" = "NSNuiober": 

"AppleEventCtsde" = "InUp": 

h 

It 


S ket C h *s c riptTe rnL no1o gy: 

"Line" - ( 

“Name" “ "line"; 

"PluralName” - "lines": 

"Description" - "A line graphic."; 
t ;ics; this was mining 7 

"Attributes" = j 

"starisAtbowerLeft" ■ I 
"Name* _ "goes up": 

"Description" * "line goes uphill or line goes 
downhill"; 

I: 

h 

h 

Step 4: Kinor diffs in other parts of source code: 
diff B *r 


/System/Deveioper/Exampl es !AppKit/Ske tch/DocUr»entKodel.subpro j 
/Image.h 

/Network/Users/andrpw/CURRENT/MCTECH/AppleScripf/SkerchScript 
/DocumentModei .subproj/Image.h 
15al6,17 

> // antfrcw addilkm 

> NSString *_£OureeFileNatnc; 

25aZ8,3l 

> 

> // ib r applescnpring: 

> (void)setimageFile: (NSString *)fileFath: 

> - (NSString *)imagcFlle; 

diff -B -r 

/Sy nt em/Developer/Exampies / AppKi I / Sket rh / PocmnentModei . subpro j 
/Image*m 

/No t wo r k / Uo e rn / a nd rev / CURRENT / MACTECi I / A pp 1 eS c ript/ SketchS c ript 
/Document Model, subpro j/ Image .m 
31 an 

^ if (_sourcefileNainc) [newObj 
set£piageFile:„sourceFileNamc]: 

169a170 

> NSString ‘SourceFileKey - #"SaurceFlle"; 

175al77 

> if CaourceFileName) [diet setObjeet;_sourneFiieName 
torKey:SourceFileKeyl; 

1953198.201 

> obj - [diet objectForKoyiSourceFileKeyi; 

> if (obj) ( 

> sourceFiieName * [obj copyWithZone:[selt zone]J; 

> i 

204a211 

> _eourceF11 eName = [filePath copyWithZanc:[self zonejl; 

211 + 212c 21B 

< // Hits is really a *wrilc<ml) j tiribuic used fur selling U k image far an l magr tfiape 
imm a script Wc don l remember ihc ft«h so the ;n.ccNSur just alums an crnpn r siring, 

< return 

> return sonrceFiieName; 
diff B r 

/System/ Uevelrjpcr/Kxamples/AppKit/Sketch/OraphicVicw.m 
/Ne two rk/Use r s/and r owf CUR RENT/HACTECH/AppieSc rip t/Sk ct cbSer Tpt 
/GraphicView ,m 
557,558c557.559 

< Lnewlroage set Image :contents); 

< [contents release]; 

> // R>r applesciipt -> so ii remembers wbctv ii came from.,. 

> [newimage setTmagaFile;filename]: 

[contents re 1 case]: // not used, bul g^iod ftir te-sling if image 

was \;ilid 
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A Sample .Script 

Once you’ve made the changes, ar downloaded the source from 
www.stone.coni/dev/SketchScript, unci built Sketch, bunch it. You cun 
make a document, and save ilic script, and then execute it in 
ScriptHdilor, Here’s ;i sample script: 

tell application “Sketch" 

wake new document at before front document 
tell the front document 

make new circle at before graphic 1 with properties fx 
position;69, y position:106, width:179, height:166, strokr 
color:“0.000000 0.000000 O.OOOUOD". stroke 
thickness:! ,000000, yLruked : 1, fill color: “1,000000 0.24493$ 

0.S5568G\ filled! il 
tell circle 1 
end Loll 

njtike new text area at before graphic 1 with properties 
U position:37. y position;!7, width:260, height:75. stroke* 
color:"Q*€00000 0,000000 0,000000". stroke 
thickness:1,000000. stroked;!< till color:"1,000000 1.000000 
1.000000", fi11ed:0. Iexi contents:“HELLO Wo r1d1"3 

set the font of the text contents of text area 1 to 
“Helvetica" 

set the size of the text content& of text area 1 to 66 
set the color of the text contents of text area 1 to 
“ 0,000000 0,000000 0 . 000000 - 

set the size uf characters 2 through 2 of the Text 
contents of text area i to 24,00 

set the color of characters 3 through 4 of the text 
contents oT text area 1 to “1,000000 0,53/40! 0.441758“ 
eel the size of characters 3 through 4 ot the text 
contents of text area 1 to 48.00 

set the size of characters % through 5 of the text 
contents of text area 1 Lo 24.00 

set the font of characters 2 through 5 of the text 
contents of text area 1 to "Futura" 

net the color of characters 5 through / uf the text 
contents of text area 1 to “0.000000 0.000000 0,000000- 
set the size of characters 6 through 7 of the text 
contents of text area I to 64,00 

set the color of characters B through J1 of the text 
contents of text area 1 to “0,504702 O.287770 1.000000" 
set the color of characters 12 through 12 of the text 
contents of text area 1 to “0.000000 0,000000 0.000000" 
set the size of characters 8 through II of the text 
conLents of text area I to 24.00 

set the size of characters 12 through 12 of the text 
contents of text area 1 to 64.00 

set the font of characters 6 through J2 of the text 
contents of text atea 1 to "Helvetica" 
tell text area 1 
end Loll 

make Fiew circle at before graphic 1 with properties lx 
position:I03. y position:I 43, width:40, height:35* stroke 
color;-0.000000 0.000000 0,000000”. stroke 
thickness;6.280000, stroked;!, fill color;"I.000000 J.OQOOQO 
1.000000", filled:0| 

tell circle 1 
end toll 

make new circle at before graphic I with properties lx 
position:176. y position:146, widUi:40, height:35, stroke 
color:“0.0O0O00 0.000000 0.000000". stroke 
thickness;6,280000. stroked:!, fill color;"!.000000 1.000000 
1.000000“, filled;01 
tell circle 1 
end tell 

roako new rectangle at before graphic 1 with properties 
lx position:102, y position:209, width;111. height:18. sirokc 
color:"0,000000 0,000000 0,000000". stroke 
thickness;4.740000. stroked;!, fill color:"0,360790 0.192160 
1,000000", filled:II 
tell rectangle 1 
end tell 
end tell 
end tell 


Gotcha! 

If you get errors when running your AppleScript, here are some 
of the posable causes and tiling to look out for: 

1 Did you remember to provide terminology (such as “goes up w for 
line's startsAtLowerleft attributed 

2, Did you correctly spell the Apple Script term? 

3. Is there a name space collision between classes, commands or 
attributes? Apple Script can get confused if commands and classes 
have the same name! 

h. Are your Apple Event Codes unique? Use uppercase lo 
disambiguate from Apple's. 

5. Are you using a synonym in an attribute? Thai won*I work! 

6. While writing your suite definition or temiinology, you might 
make a syntax error and tire list Ixxxmies “linpameable" I 
recommend that you download and install Mike Penis’s excellent 

lextiLxtras" framework from www.lorax.cXHi) which installs many 
useful text processing functions into every Cocoa npp using tlie 
input manager architecture. One feature that you’ll find extremely 
useful tor Apple Scripi design is the “Parse as Property Usf menu 
item: select your definition and choose this item to see if there are 
any typos or missing semi-colons. 

7. Quit Early. Quit Often: II you change your suite or terminology, 
lie sure to quit SeriptKditor and relaunch it, since it illicit cache 
llie old dictionary. 

8. You must quote strings and paths. 

9. UememlxT. in OneToMa nyUclationships, use the Apple Event 
Code of the class of object stored in the anay or dictionary. In 
allrilrules, do not use the attributes class axle, hut create a unique 
one. 

Known Bugs 

Developer Preview 3 

BUG: NSUnkix>wnKc\ r ScriptError when executing statement; 

"make new tloaunent at liefore front dcxiimenf 

*** -{NSDcx^umeniControIkT _addDncument:t seleaor not 

recognized 

WORKAROUND; none make a new ckjcuimml manually and 
compile compile with -DDP3 for commented out code. 

BUG: Where is application “Sketch"? And it l wrings up an OpenPanel,,, 

WORKAROUND: compile with -DDP3 which will use “Sketdiapp" 
which does work. 

GONOUtSftON 

It’s easy and rewarding u> add AppleScript to your application, 
and its a lot of fun to watch a script execute and makes a fearsome 
demo, but more importantly, it adds great value to your application 
because regular users can automate work flow and "program" your 
application to do various tasks. 
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WEBOBJECTS 


By Patrick Taylor and Sam Krishna 


Introduction to EOF and WebObjects 
The State of WebObjects 


Before we talk about state management in WebObjects 
we need to digress a bit because Steve Jobs lias blasted one 
out the park... 

Just before press time, Apple announced that the price of 
WebObjects was going to be slashed. As we mentioned last 
month, WebObjects was designed for Lhe kind of demands 
that an Apple Store-like web site might bring to bear, this is 
not your father's web application server. Because it is 
enterprise level software, it has had a correspondingly 
enterprise level price — a shocking $S0,000 for a single high’ 
end deployment license and another $1299 for the 
development tools. At least that was case until the WWDC 
keynote where Steve Jobs announced that effective 
immediately a combined development and deployment 
license was going to be sold for $699, 
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WebObjects is now within the means of practically any 
web developer -— projects which needed that class of 
middleware, but couldn’t justify the price, are now very 
possible. A WebObjects, Mac OS X Server and Frontba.se or 
Open base combo is now price competitive with Windows 
2000 Server (which includes IIS and does dynamic publishing 
via ASP), Visual Studio and SQL Server even when you 
consider higher comparable Apple hardware prices. The 
combination of Linux and one of the growing number of 


open source dynamic serving solutions (like Zope) are 
probably still cheaper but having the lowest initial price has 
never been Lhe real reason for choosing this environment. 

Speaking of Reasons for Choosing WebObjects 

With the rise of XML, Java Server Pages, Perl/Pylhon/PHP 
and JDI3C, it’s quite common to have people asking “If all of 
these standards are becoming more popular, why should 
anyone bother with WebObjects (especially wlien it still had 
ids transaction limitations leased on the price you paid for the 
license)?* It certainly is possible to do almost anything that 
WebObjects can do with some combination of pre-existing 
tools and hltxxl, sweat and Lears, however, WebObjects 
manages many things for you, things you get as part of the 
standard package. 

And one of the most important things is State 
Management. State management allows the server to be 
aware of the interactions by numerous clients each 
ensconced in their own session. Since H'lTP is normally 
stateless, both the browser and the server will forget about 
client-server interaction as soon as a particular transaction is 
finished. One it hands of data from a form, a browser will not 
remember any values or selections made. This can be both a 
hassle and a security problem fore-commerce. 

In the previous article when we discussed the request- 
response loop, we saw how WebObjects normally uses the URL 
to manage state over Lite life of a user’s session. Since an HTTP 
server naturally assumes that every single request it receives 
from remote users is a unique transaction, it becomes necessary 
to overcome this hurdle. Normally, the protocol does not allow 
slate to be preserved so il becomes nessary to piggyback on 
pre-existing feature transmitted back and forth between the 
client and server. Options include maintaining state via the l iRL t 
with a cookie, or more rarely a hidden field in Lhe HTML, As 
well you can store this session information in the database to 
provide for long-term continuity for your users. Or if you have 
very demanding applications, you cm even use multiple state 
management strategies. One example would lx- a sophisticated 
e-commerce site using a combination of cookies (to identify a 
client), database entries (to maintain history) and hidden fields 
(to maintain session integrity without littering the URL). As well, 
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it is also possible to maintain state without embedding session 
i n ft >rm alic m u si ng D i ret I At tic ms. 

State management has benefits beyond just providing a 
“history” between users and the site. It also allows 
WebGhjeets to keep business logic on the server since session 
information is preserved, thereby avoiding the security risk of 
unscrupulous modification of client-side business logic (the 
Internet version of the “five digit discount*). It also provides 
some security for the user by not embedding sensitive 
information (like credit card numbers) in the HTML and 


But why would WebOhjec/s need to piggyback on 
ex is ting featu res? 

Because they are there. Seriously ... rather than 
reinventing ways of interacting with servers and 
browsers, WebObjects takes the path of least resistance 
by using whatever already exists as a standard feature 
in the most effective way possible, in a welt designed 
WebObjects application, it is possible to use Lynx (so 
long as it supports a recent vintage of the HTML 
standard) to browse a page, Unlike Microsoft's "works 
best with Internet Explorer and/or Windows” appmach, 
WebObjects is philosophically inclusive. 

Consider the case of someone who didn 1 piggyback 
on existing standards: recertify some wide-eyed and bushy- 
tailed dotcom announced a new banner ad format that 
would give web developers far mote flexibility than is 
avalable with the etmpreseni cgi-based animated gif 
banners The deadly flaw is that it um based around a 
new plug-in. Now maybe the developers had come up with 
a brilliant way to get people to download an advertising 
specific plug-in, hut while most users accept banner ads as 
an acceptable annoyance or even a necessary evil, notone 
person in a hundred is going to download such a plug-in 

Take this story as a cautionary late, it does not pay to 
make users download plug-ins, especially if you're trying 
to sett them something, 5b // a strategy that uses built-in 


through the complex machine-readable session information 
(the complex gobbledigook on the URL) makes it very 
difficult for anyone to hijack a session from a user. 

Applications, Sessions, Components, Oh My! 

The WebObjects engineering Leam solved the state 
management problem in a very clean way. Intrinsically there 
are three levels a programmer will ever want to store state 
within a web application: the global level t the user level, and 
the page level Within WebObjects, this is known as the 
Application/Session/Component state management system. 


Why is State Management good for developers? 

WebObjects isn’t unique in providing state 
management There are plug-ins for NSAPi and tSAPl 
can he used to provide some degree of state 
management, WebObjects manages to provide state 
management even on lowly COL By filling in" the 
missing featu res from one adaptor to the next 
WebObjects manages to provide a consistent target 
which developers can depend on so that developing an 
application which uses CGI isn't different than an 
application which uses an ISA PI connection. Besides 
consistency this simplifies the process of transferring 
applications from one platform to another. Tor 
example ; you could do your development on a 
PowerMac G4 running Mac 05 X Server L2 with 
Apache 1.3* 12 and then deploy on a SPARC Workstation 
running Solaris 8 using iPlanet Web Server. Short of 
changing some configuration sellings and 
recompiling, very little needs to be modified to make 
the transition. In future articles, we ll see how a similar 
situation plays out with databases and their adaptors, 


For the Application layer, there’s a class called 
WOApplication used to manage the entire run-loop of a 
WebObjects application as well as define and access very 
specific application-wide behavior. There is a 
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programmer-accessible subclass of WO Application simply 
called Application where you can store, for example, an 
array of the New York Times Bestseller List of books that 
every user can access when they visit the site. You can 
also define the behavior for what happens when a user 
does something illegal (like invalid form values) and 
redirect them to a page saying they need to re-input their 
information. Because Session and Component (page 
classes) derive from and fall under Application, they have 
access to all features added at the Application level. 

For the Session layer, there’s a class called WO Session 
which lays out the basic behavior of a user's session with 
the app, The session represents the complete lifecycle of a 
user's interaction with a WebObjecrs application. The 
WOSession class has a subclass called Session which 
provides programmatic hooks for a developer. This subclass 
inherits a collection class called an NSMutableDictionary 
which can be used to store information beyond just she 
instance variables that have already been defined. For 
example, the Session can be used to contain a shopping 
can with credit card information, books selected, and other 
various and sundry items. 

In the Component layer, there's a class called 
WOComponent which manages all of the general 
interaction with the request-response loop and the actual 
hooks into a given HTML page for direct access to 
instance variables. You can literally create a new page, 
create instance variables for that page, bind the instance 
variables to the HTML elements on that page, and, after 
all that, have a functional — though slightly homely — 
web page without having to write much code. 

The Component subclass is responsible for interacting 
with the WebObjects system to generate all of the HTML 
on-the-fly for a particular page based on the state of the 
information to be displayed and what the developer has 
Instantiated in the Session and Application objects. The 
component can ask the session and the application 
objects for any particular state that the developer sees fit 
to access. A Component can be used to display the detail 
information and a particular image to represent a book 
currently browsed by the user. 

What's so amazing about this system is dial after you 
stall using it for a while, you 11 wonder why anyone worries 
that the Web is a stateless system at all 

So many different ways of managing state 

We have already have explained some of the 
mechanics of storing session information in the previous 
article on the request/response loop. A WebObjects 
application by default stores the session ID in the URL 
automatically along with the component ID. Some 
developers (and users) don't care for the long URLs with 
machine readable session data partly because they are 
ugly, but as the least invasive method to maintain state. 

Cookies are a useful way of tracking transactions but can 
be problematic. Not everyone enables cookies In their 


browsers so you may turn people away if you make your site 
cookie dependent. It is possible to request that the Session 
object store the Session ID in a cookie instead of in the URL 
(which ii does by default). You can send the message to your 
Session object like this: 

In Java: 

session () .set5toresIDGlnCooki.es (true): 

In Objective*C: 

[[self session] setStoresIDsInCookies:YESl: 


This code will force the session to stuff all session ID and 
element ID information into a pair of cookies named “wosid” and 
"woinst”, respectively. These two cookies keep all session ID and 
dement ID information LhaL normally would be in the URL and 
keeps too much of the session "noise" from littering the URL. 

The basic way to use a cookie for state management is 
by simply instantiating a WOCookie object 
In Java: 

WOCook1 e. cook 1 rW i t hNnme (* n omcNamp.") 

In Objective C; 

tWOCookie cookieWUbNume ;^*sameNaine‘ f ] 

Then it is possible to set the name, domain 
information, expiration information, path information Of 
applicable), and finally its value (the actual state 
information you want to store). 

To do this, you would probably want to override public void 
appendToResponseQ in your Component subclass. You would 
do this in ObjeaiveC with appendToRGsponse:inContext: 

The sequence would look something like this: 

In Java: 

public void appendToKeaponEB(WOResputiEie response. WOContext 
context] I 

// Assume for sake of example ilia: we re generating cookie for first time 
//Also assume that password Value is an instance variable prebound to some secure 
text field that the Component knows about 

// Set expiration date for one month from now 

NSGcegorianDate onoMorithFromToday ~~ new NSGregoriaititeteO ; 
o rt eXont bS r omTo day = 

OtieMonthFromiod^y>Oat^ByMdiugGregorIanUsits (0< 1, 0. 0 * 0, 0); 

WOCookie cookie = WOCookie. eookieVithNante( “password" . 
password Value, null, "ww, mydonain * coin'". oneMonthFromToday. 
fslse): 

response.addCookie(cookie); 
return: 

) 


In Objective-C: 

- (void)appendToResponseUWOResponse *) response 
inCont ext:(WOContext *}context 
\ 

//Assume for sake of example that we're generating cookie for first time 
// Also assume that passwordValuc is an instance variable ptebotmd to some secure 
text field that the Component knows about 

// Set expiration date for one month from now 

NSCalendarDate # oneWt>nthFro»Today - [NSCalendarDate 
calendsrDate]: 

WOCookie ‘cookie ■ nil: 
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Erratum 

fn the historical list ofWebObjects team members ; we 
gave last month some people were accidentally left out 
The WebObjects 3*5 and 4.0 teams included Lament 
Romontianu and Patrice Gautier. Charles Lloyd left the 
team after WO 4.0 (and eventually ended up at Ariba 
with Craig Federighi). 

P _ _ 

oneMqnthFroniToday “ [oneMonthFroinToday rfatefiyAdd IngYearsiD 
months:1 days IQ hours:Q tnimiten :<) seconds:Q]; 

cookie 55 [WOCookie rook \ 3ThName;®"password" 
value; password Value path: n f 1 riomairu@ M www, my domain, coin" 
expires :oneMom HFrowTudiiy isSeciire;flGj : 

[response. addCookie:cookie]; 
return; 
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Direct Actions and Slate Management 
without Session information 

There is another type of UHL state management known as 
a Direct Action, a type of WehObjecr class that can track 
information without a session, taking stale from one 
component and passing it to another component via die URL 
For example, a Direct Action object can be used to track tire 
user Il> and the password of a user in tire URL All the state 
information will be passed through the URL The advantage of 
tills is liiat you have the ability to bookmark pages within a 
WebObjects application (since version 4 of WebObjects), 
However, the downside of this is that a developer now has to 
ihink alxjui the implications of not having a session and 
having to manage .stale from component to component. 

All Direct Action methods should be defined in the 
WO Direct Action subclass called Direct Action, It is 
common convention that all the action methods end with 
the word “Action” in order to be distinguished as direct 
action methods. As well , when using Direct Actions, 
debugging is simplified if you name your WOTextFields 
and other input elements with meangingful names. 
Otherwise, the WORequest object will assign arbitrary 
names for your input elements and make it practically 
impossible for you to access your input variables unless 
you choose to conform to their arbitrary naming style (i.e. 
using latent ESP while programming direct actions and 
using the method ta ke Values From Request() or in Objective- 
C - take Values From Request: inContext: to access form values 
from a WORequest) 

End of Session 

Having received a taste of WebObjects in die last two 
articles, it’s time to jump to something different. Next month, 
well go back to EOF and look at FOMcx lei ling. Is it relational 
or is it object-oriented? It’s the entity-relational system that 
tastes great and is less filling. HO 
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Since 1991, high tech companies like Apple Computer, 
Hewlett Packard, and Leica Microscopy have turned to 
Art & Logic for assistance in implementing cutting 
edge technologies. 

Now, with the advent of OS X, Art & Logic is helping 
companies make their products compatible with 
Apple’s new operating system. Art & Logic engineers 
are industry leaders in Carbon & Cocoa porting, Aqua 
implementation, and driver development. 


"We have found the engi¬ 
neers at Art & Logic to be 
outstanding—better than 
excellent. When we use 
their software development 
services, we get results.” 

Ted Dykes, CEO of LRO. Inc. 


The software engineering company that helps bring your 
hardware product to market—guaranteed. 


In the new economy, where time to market is every 
thing, you need results. Art & Logic delivers. 


Art & Logic, Inc. 
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□ Eat your vegetables. 

H Exercise every day. 

2f Port to Mac OS X. 

□ Call your mom. 

! All of these are good for you. 

I We can make one of them easy. 


Since 1989, The Omni Group has worked wilh ihe technologies that have been refined into Mac OS X. 

Moving to Mac OS X is a big step for your company, and you need consultants who can help you both 
plan how best to make the transition and follow whatever path you choose. 

That's been our business for years. No mailer what kind of product you have, we can gel it up under 
OS X, fast: 

• Rea) games: We ported id's Doom and Quake games to NEXTSTEP and OS X. Quake 2 took us a week. 

• Big apps: We ported Adobe's Frame.Maker to NEXTSTEP and Sun’s Concurrence to OpenStep 'Solaris. 

• Big libraries: We ported the Oracle 8 client libraries which Apple ships today in OS X Server. 

• Serious drivers: We ported 3dfx’s Glide and wrote Voodoo2 and Rendition drivers for OS X Server. 

We've written new mouse drivers for OS X Server and joystick drivers for OpenStep. 

• New apps: We wrote OmniWeb, the only native OS X web browser, and OmniPDF. the native Acrobat 

viewer for OS X. 

Mac OS X is what we do. Let us help you do it, too. 


The Omni Group 



2707 Northeast Blakeley Street 
Seattle. Washington 98105-3118 
www.omntgroup.com consulting 


sales^om nigroup.com 
800.3IS,OMNI x20l 
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Call Red Rock Software at 888.689.3038 or visit us at www.redrocksw.com 
Aqua Interface Implementation, Carbon 
Porting to Mac OS 8, 9, X, and Cocoa Application Development. 
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With over thirteen years in providing 
programming service to the Mac community. 
Prosoft is committed in delivering the ultimate 
quality software products and service. 


Our Engineers have extensive knowledge in: 


Macintosh PPC Drivers, 
Shims and Extensions 
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Applications, Mac OS X 
applications and drivers 


Carbon application 
porting for Mac OS X 


• Multimedia and QuickTime 
Applications 


Unix/Linux Console 
Applications, including 
Unix Solaris, xBSD Drivers, 
and Linux Drivers 
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TOOLS OF 
THE TRADE 


By Bill von Hagen 


Equilibrium’s DeBabelizer 


♦ 

Automating graphics 
processing, conversion, 
and manipulation 


The Tower of Babel is Lhe biblical tool 
of multiple languages on the planet earth* 
DeBabelizer 1 s name suggests that its goal 
is to cut Lhrough Lhe confusion of multiple 
graphics formats* This would be a 
pretentious product name (which has 
never really affected product naming 
before) if it wasn’t essentially true* Simply 
put, DeBabelizer is the best graphics 
manipulation software I’ve ever used on a 
computer that \ could actually afford to 
own and fit in my house. 

DeBabelizer provides an impressive 
number of powerful graphics file 
manipulation, transformation, and 
conversion commands. To simplify 
performing the same transformations on 
large numbers of files, DeBabelizer 
enables you to store sets of 
transformations and apply them across 
user-defined sets of graphics files. Though 
batch processing is something of a 
anachronism in today's GUI-based 
personal computer software, sometimes 
it’s exactly the right thing* I’ve used earlier 
versions of DeBabelizer for years to refine 
screen captures from Windows and UNIX 
systems for use in help files and printed 
documentation* My goal is usually to 
convert them into another graphics 


format, resizing them without sacrificing image quality, and 
reducing the numl>er of colors used. In this sort of situation, you 
need to make sure that you apply exactly the same set of 
transformations to Lhe entire set of files so that you don’t 
subsequently encounter any color or size surprises when using 
the converted files. DeBabelizer shines at this sort of task. 

Any modern graphics tool ignores the needs of the World 
Wide Web (and, to a lesser extent, those of other graphics 
packages) at its peril and to the detriment of its sales. 
DeBabelizer can quickly transform any input graphic into the 
GIF, JPEG, or PNG graphics formats used on lhe Web, 
DeBabelizers other output graphics formats range from the Ole 
formats used by specific graphic packages such as Photoshop, 
Degas, and Pixar's graphics tools, to basically every "standard* 
graphics format that anyone has ever proposed* (In fact, there 
are so many of them, that you will wonder if standard is the right 
word, hut as the old saying goes, "You are in a maze of 
conflicting standards, all different.”) Users of Apple H graphics 
packages will rejoice that classic output formats for the GS, ][e, 
Ik, and 1+ are available, and users of high end systems like SGI 
boxes and the Sony PlayStaLion will be similarly pleased to know 
that their graphics format needs haven’t been overlooked. 

Using DeBabelizer 

There are three basic ways of using DeBabelizer* First, you 
can use the tool interactively, performing specific transformations 
on a single file. Used in this way, you explicitly open a file, do 
the transformations, and then save the file with any name you 
want. Second, you can create a DeBabelizer script consisting of 
a set of transformations onto which you drag and drop specific 
images to manipulate them. This type of script generally includes 
a command to save the file, using some clever mechanisms 
provided by DeBabelizer for giving your output files unique and 
different names. Finally, you can create DeBabelizer scripts that 
only consist of a set of graphical transformations. The list of input 
files and the naming rules to use for your output files are 


Bill van Hagen is a writer, computer system administrator, and die author of "SGML for Dummies." You can contact him at 
wvh@gethip.com. 
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specified in either the Batch list or Batch Automation dialogs. 
Hie Batch List dialog lets you define a fixed set of files that you 
want to transform in the same way. The Batch Automation 
dialog lets you define a temporary set of files that you want to 
process using a specific script. Complex? At first. The right 
thing? Yes, but it takes a bit of getting used to, 

DeBabelizer provides complete online help in its own 
formal. Many Macintosh applications provide help as balloon 
help, which Is always cute but often useless, or external 
DocMaker or HTML files, which are heller than nothing but can 
be inconvenient to use while you’re actually running an 
application. DeBabelizer provides complete online help in its 
own format. All DeBabelizer dialogs contain a Help icon (a 
question mark) I hat automatically jumps Lo the relevant section 
of the help file for that dialog. You will definitely find this useful. 

Creating DeBabelizer Scripts 

Creating a script to process one or more images is easy. You 
first open an image that is characteristic of the set, then open 
De Babel izer's Script window by selecting the Window menu s 
Script command or by clicking on the Script Window icon in the 
toolbar {the fifth icon from the left). The Script window, shown 
in Figure 1, enables you to define the sequence of 
transformations that you warn 10 apply lo a sei of graphics files. 

When creating a script, you will usually want to open a 
sample image from the set dial you want to process with the 
script that you’re creating. Why open a graphics file first? 
Because, as mentioned previously, scripts define a sequence of 
transformations that you will apply in batch mode to some 
number of different files You therefore don't want your script lo 
explicitly open a single file, bui milter to l>e able to transform 
any file lhal you drag or drop onto the script or feed to the script 
as part of a batch list. Specifying the list of files lo apply the 
script to is done using DeBabetizers Batch Automation and 
Batch Lisi dialogs, which are discussed later in this review. 



Figure 1. DeBabelizer's Scrij)l Window. 


The Script Window 

DeBabelizer s Script window consists of three areas 
surrounded by handy icons for related commands, The Lop 
portion of the window displays three preview windows that let 
you examine your image as you apply transformations. To 
activate these windows, dick Preview in Live upper left portion of 
the Script window. The window at the left shows a reduced 
image of your entire graphic, overlaid with a green selection 
rectangle thar lets you focus in on any portion of your graphic. 
To view any portion of your graphic, click and drag the selection 
rectangle to include the portion of the graphic that you want to 
view The other two windows show a magnified image of the 
selected port ion of your graphic before and after applying any 
DeBabelizer transformation. This previewing and selection 
feature makes it easy for you to check the effects of a 
transformation on different parts of your graphic without having 
Lo exit the .scripting process. The fact that you automatically see 
a magnified selection from your image is convenient for verilying 
thar color transformations lhat are important in one pan of your 
image don’l negatively affect others. 

The middle section of the Script window consists of a set 
of menus that provide access to the DeBabelizer 
transformations thuL were initially available from the 
DeBabelizer menus and toolbar. When working in the Script 
window, you can't access either she main menus or the 
toolbar, so the menus are conveniently replica Led here for 
use during the scripting process. Many scripting tools use a 
"remember what I do” model when creating scripts, I find 
DeBabdizeris scripting method, where you assemble the 
script in a specific scripting dialog, lo be less prone to errors 
because this makes ii more difficult to accidentally add an 
operation that you don’t want to perform. One unfortunate 
aspect of the menus as provided in the script window is that, 
while you can scroll Lo submenus in standard Mac style, you 
can l scroll from one menu to the other without re-clicking 
the mouse button on the new menu you want to select. This 
is a minor irritation, but still Lakes a bil of getting used to. 

The bottom section of the Script window displays the 
title of the current script above a Script View window that 
lists the specific DeBabelizer transformations and other 
operations in the order that they are lo be performed in the 
script* The Script View window makes it easy for you to see 
what any script consists of and simplifies removing or 
resequencing specific operations within the script. You can 
imagine that DeBabelizer provides hundreds of different 
transformation and image manipulation operations-being 
able lo drag and drop operations to resequence them is 
extremely handy-as is the quick removal of operations if you 
find a better way to improve a representative images. 

Once the Sc ripi window displays, you will first want to 
assign a meaningful name lo the script you’re creating. To do 
this, click on the heading button over the Script View window. 
A dialog displays in which you can assign a new name to the 
script you are creating. By default, new scripts are named “New," 
followed by the date and time that they were created. This is 
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|X)ssibly more useful than using a generic name if you forge* to 
name a script but rememfxr when you were working on it 

Specifying Graphics Transformations in Sckifis 

Image transformation and manipulations fall into two 
general categories. Some are atomic operations that can infer 
any information that they need from an image itself {such as 
rotation, basic trimming operations, and pre-scaied image 
resizing). Others are operations dial require spec ific parameters, 
such as resizing an image to a specific, user-defined size, 
selecting a specific blur or color reduction method, and so on, 
Scripting operations that require no external information is 
easy-they simply appear in the Script View window, Scripting 
parameterized operations is conceptually a more complex task, 
since you need to be able to add those parameters to your script, 
luckily, DeBahelizer makes tills quite simple. 

When you add an operation that requires parameters to 
a script, its name in the script window is preceded by a dark 
question mark. This indicates that DeBahelizer needs more 
information to complete this operation. Double-clicking on 
that operation displays a dialog in which you can define the 
options and arty numeric parameters that you want to use, as 
shown in Figure 2. 



| G»nctl | | Help*. [ \ More | 


Figure 2, Sfnotifying Options for Parameterized Ojwmtiam. 

The Scale dialog requires several parameters: the operation 
to perform, the target width and height if you are staling to 
specific pixel dimensions cither than to percentages, anti the 
transformation method used to maximize the quality of the 
scaled image. To sjxrrify the values you want for whatever 
options are shown on the screen, just select them and clic k OK. 
If you’ve forgotten to complete any mandatory parameter, 
DeBahelizer displays an error message, indicating the parameter 
that you need to correct and why the current value is invalid. 
Once you've specified values for all mandatory parameters, 
clicking OK returns you to the Sc ript View window, and a small 
“QIC symbol replaces the question mark, letting you know that 
the script step has all of the information you want. 


like all powerful programs, DeBahelizer has options on top 
of options, many of which you will rarely (perhaps never) use. 
To minimize DeBalxdizers intimidation factor, the authors have 
thoughtfully grouped the most common options on the primary 
dialogs, and made the more advanced options available only if 
you click the More button on any screen that provides advanced 
operations. Figure 3 shows the same dialog as in Figure 2, bur 
after clicking More to expose additional options. In this case, die 
Dither Indexed Color Images and Anti-Allas options are both 
considered advanced options. If you want to provide values for 
any advanced options, just set them and click OK while the 
advanced options are displayed. DeBahelizer remembers that 
the dialog shows more options, and automatically sets them 
when running that step of the script. 



Figure J. Advanced f iptiom for the Scale Dialog. 

Missing Transformation Warnings 

While DeBahelizer prompts you for all of the information 
necessary to complete a specific transformation, there are 
cases when subsequent sleps in your script will require 
transformations that you may not have included in your 
script. For example, in my testing l found that saving graphics 
in output formats that have specific color limitations 
generates a warning message if your scripi doesn't specifically 
include a color reduction step. The example developed in this 
review creates a sc ripi that accepts input files with unknown 
numbers of colors and saves them, after transformation, as 
256-color TIFF files. Figure 4 shows die warning message 
generated by DeBahelizer by the Save step when my script 
didn't include an explicit color reduction command. 
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Figure 4. A Sample Warning Dialog 
far Missing Jmm/onnations, 

Not recognizing a missing step when creating a scrip! isn't 
necessarily a flaw-it would Ik: incredibly time-consuming (and 
probably irritating for the user) for DeBabelizer to analyze the 
relationship between each step and its successor as you create 
your scripts. Delia! jelizers compromise solution, warning you 
when a subsequent step requires an operation that isn’t 
explicitly part of the script, provides a good balance lxaween 
expediting the script creation process and making sure that your 
script contains all of the mandatory transformations, 

When a missing step is detected, warning dialogs such as 
the one shown in Figure 4 include the option for DeBabelizer 
to automatically perform this .step in the future, eliminating the 
warning and the dialog. Unfortunately, accepting this automatic 
remapping seems to lie a global Boolean when 1 tried 
rerunning other versions of the same script that 1 had saved prior 
to accepting this value, ihey automatically did the color 
remapping, too, 'this is probably the right ihing in some sense, 
but was unexpected. 

In general, when DeBabelizer displays a missing step 
warning, the right tiling to do is to add the specific DeBabelizer 
commands to your script to explicitly perform the missing 
operation. Though DeBabelizer will fill in the blanks for you, 
doing so makes for hard-to-maimain scripts that reek of magic, 
because all of the operations they perform aren’t explicitly listed. 

Saving Converted Graphics Fills 

If you are creating a script that you will use by dragging and 
dropping images onto it, the final step in a your script is to save 
the transformed graphics file. If you are creating a DeBabelizer 
script that you wall apply to a batch of files, the automatic output 
file naming options discussed in the next sen ion of this review 
are built into the Batch List dialog, 

Unless you have more skill (or ego) than any supreme deity 
gave the rest of us, you will always want to preserve your 
original graphics until you're positive that the transformed 
graphics are suitable for your purposes. Verifying your images in 
another graphics tool, layout tool, or over the web can Like 


some time, but only the foolhardy or the incredibly lucky tend 
to skip titis step. Saving your modified graphics while 
preserving the original files is an interesting proposition, since 
the only file name that DeBabelizer knows is the name of the 
file that you originally opened in the too], As you’d expect, 
DcBaixdizer addresses this * problem" in a powerful, flexible 
way via the naming options provided on its Save As dialog. 
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Figure 5. Standard Options on the Save As Dialog 

As shown in Figure 5. the standard Save As dialog provides 
an easy way of guaranteeing that you don't overwrite your 
original files with the transformed versions; by saving them to a 
different directory. The Save As dialog lets you navigate to or 
create any other folder and specify that folder as the location to 
save the transformed files. This would suffice, but Isn't 
necessarily a very elegant solution. 

I )eBabe I i zer pit>v ides i n< >re sopi 1 1st ica let 1 output file naruing 
options in the more advanced version of the Save As dialog, 
available by clicking More. The resulting dialog is shown in 
Figure 6. The more advanced Save As dialog adds output 
options for applying another DeBabelizer script as part of the 
save process, automatically generating a picture icon lor the 
saved graphics file, and provides access to a sophisticated Auto 
Naming dialog with more Ixdls and whistles than the cathedral 
at ClKiilres. The Ault) Naming dialog is shown in Figure 1. 
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Figure 6. Advanced Options on the Sate Av Dialog 
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DilBaui lizkr's Airro Naming Diaijog 

DeBabelizeris Auto Naming dialog provides three basic 
naming mechanisms for transformed files: based on a user- 
specified text siring, based on the original name of the file, or 
using a combination of predefined variables and information 
about the fife itself. The first rwo options are fairly 
straightforward, but the third option deserves a closer look. 



Figure 7 Save A? OptUms for Automatic File Naming, 

\ use DeBabelizer on my Mac to dean up and transform 
images front a variety of different systems including the 
BeOS, Windows, Macs, and multiple flavors of UNIX. I 
usually need 10 standardize their dimensions, color depLhs, 
and output formats for use in documentation and Web 
publishing projects. Because l don't always have easy access 
to the systems on which I generated screen shots. ] can t take 
the chance of overwriting files, though l like to keep 
everything in single, per-project directories. F.ven though the 
Mac doesn’t require them, 1 like to use filename extensions 
to quickly identify the type of a specific graphics file. The 
Auto Naming dialog's Build name + extension for Save Type 
command does exactly what I need, letting me append the 
string “converted to the beginning of each output file, use 
the original file name as the remainder of the file's 
basenume, and then append an extension that indicates the 
graphics output format. For example, the TIFF version of a 
processed BMP graphics file called screen 1 would be named 
converted_SGreen1 .TIF. 

Testing DeBabelizer Scripts 

After completing your scripts but before saving them, 
you may want to run through the entire script* either running 
the entire script at once or single stepping through each of 
its operations. To lest a script on a sample graphics file, all 
you have to do is make sure that you’ve saved the script and 
then just drag a graphics file onto the circular icon at the 
bottom of the Script window, 

'testing a script is one of the cases in which the different 
ways of using DeBalvelizer makes things a bit more complex. For 
example, if you are creating a script that you will run on a list 
of files specified by a Batch List, your script won't include a Save 


step. You therefore won’t be able to test the Auto Naming 
options until you run the script itself from the Batch List or Batch 
Automation dialogs. 

Saving Your DeBabelizer Scripts 

Tile final step in completing a script is saving the script 
itself, which is a step in which DeBalxdlzer still has some room 
for improvement. DeRalxdizer doesn't seem to save scripts in die 
Mac file system as independent files, hut tracks and stores them 
internally. I would find it more useful to lie able to save scripts 
in the file system as standalone objects whose creator is 
DeBabelizer and which you could therefore execute by double¬ 
clicking on them. I'll discuss running scripts and sfiecifying input 
file a bit later. For now, let’s focus on saving the scripts in 
Dc Babel izers internal format. 

DeBabelizer provides two options for saving scripts, Save 
(as current name) and Save As (under a new name). Both of 
these are accessed from the Script window, by clicking on the 
Save icon (the disk icon second from the top left in rhe Script 
dialog). To save the file under a different name, hold down the 
Option key when clicking on the Save icon and enter die new 
name for the script in die dialog that displays. 

Creating Batch Lists 

Batch lists are sets of files that you can define and 
subsequently apply specific scripts or other transformations to. 
Figure 8 shows DeRabelizer’s Batch List dialog. 



Figure & The Batch f ist Dialog, 

To create a batch list and define the sets of files in that list, 
select the Batch List icon from the DeBalielizer toolbar (fourth 
from left). The Batch list dialogs displays. Click the top left icon 
to start a New batch List, or select an existing batch list from the 
list at the top of the window. To add files to a new or existing 
dialog, clicking rhe Add Files icon (third from top left) displays a 
dialog in which you can browse to any locution and add files by 
clicking the Batchlist+ button. You can even add URLs rather than 
local file locations by clicking the Add URL button (fourth from top 
left). Once you're done creating a batch list, you can save it by 
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dicking the Save icon, nr modify specific options for the batch list, 
such as its output file naming conventions, using the icons at the 
bottom of the Batch List window. 

Running DeBabelizer Scripts 

As mentioned previously, DeBabelizer saves scripts internally 
rather than in Lite Mac file system. ‘Ihe way in which you run your 
Ddiulielizer scrips depends on the type of script you’ve created, As 
mentioned earlier, there an 1 three basic ways of using DeBabelizer: 
interactively; tlirough scripts that you use via drag and drop; or 
through scripts that you invoke against sets of files sjxxrified either 
as a fixed bitch List or interactively through the Batch Automation 
dialog. Only the latter two options are relevant ro uning scripts. 

To run a script lliat you’ve created to lx* used through drag and 
drop, open the Script window, select die script you want to mn t 
browse to a file that you w ant to process, and drag it onto the small, 
round icon at the Ixxtcan of the Script window. 

To run a script that you've designed to be used with batch files, 
you display the bach Automation dialog by selecting that command 
from the bitch menu. You can also open this window from the 
Batch list dialog, by option-clicking on the Batch Catalog icon at the 
Ixjttom. The Batch Automation dialog, shown in Figure*), provides 
access to batch lists, but also lets you interactively select specific files 
(or all file's in a specified directory) to prcx:ess using a given 
DeBabelizer script. 



Figure % The Hutch Automation Dialog. 

Once the Batch Automation dialog displays, you specify die 
files, folder, or batch lists you want to process using the options at 
the top of the dialog. You (hen select the script that you want to 
use to process those files, and select the directory in which to save 
die transformed files and die Auto Naming conventions to use 
when saving those files. You can then dick Apply to execute the 
selected scripts on the specified files, lists, or folder contents, or can 
click the Exit with settings button to keep the files, script, and output 
options you’ve specified without actually executing the script 


New Feaixuucs in DeBabeijzer 3 

ITeBalxriizer has been the premiere graphics tweaking and 
inversion application for the Macintosh for years. Version 3 
improves the DeBabelizer GUI and command structure, but still 
leaves plenty of room for improvement In subsequent versions. 
Version 3 also introduces support for a few new input and output 
graphics formats, adds improved support for optimizing web 
grapink's, and improves DeBabelizeris color reduction process 
(already superior). It also provides bidirectional CMYK to RBG 
conversion, and improves DeBabdizer’s scripting language by 
adding several conditional image processing commands. 

Conclusion 

Though it’s marketed as an “automated graphics Ifilel 
processor," if I were the marketing guru at Equilibrium, I would 
market DeBabelizer as a Swiss Army knife for anyone who ever 
works with computer graphics, regardless of the platform. 
Equilibrium has ported DeBabelizer ro the Windows platform, 
which Is almost a shame-fur years. I've enjoyed being able to 
tell my clients that “I used a Mac” as my sole response when 
asked how l performed some Feat of graphics conversion or 
manipulation wizardry. CMC I, Inc. is in the process of acquiring 
Equilibrium as I write this, which should only help popularize 
DeBabelizer by increasing its advertising budget and exposure. 

DeBalxjlrzefs interface is much improved over previous 
versions, kit is .still complex and quirky. However, reaching your 
goal-in this case, high-quality image manipulation, transformation, 
resizing, and formal conversion-makes any hassles encountered en 
route seem minimal when you fook back. ESQ 
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Got Software? 


Need help safeguarding your software? If ynu re developing 
software, you need your valuable work protected with 
copyright and trademark registration. Then, when you arc 
ready to sell it, you can protect yourself further with a 
licensing agreement* 

1 am a California Lawyer focusing on Intellectual 
Property, Corporate, Commercial, and Contract taw, as 
well as Wills & Trusts* 


Please give me a call or an e-mail* Reasonable lees* 


Tlic Law Office of Bradley M. Snide rm an 


Visa 

Master Curd 


B M S 


Discover 
American Express 


E-mail: brad@smderman.cum ■ Internet: www.smdermsn.com 
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By Jeff elites <online@mactech.com> 


Preparing for Mac OS X 


Unless you’ve lieen living under a rock, you know by 
now that Mac OS X is just around the corner. At this point, 
every Mac developer should l>e preparing himself for tills 
brand new operating system. Make no mistake — Apple has 
gone to great pains to make this transition as smooth as 
possible, and to ensure the widest possible range of 
backward compatibility, but Mac OS X is a whole new world. 
Developers should be extremely excited; I know I am. But it 

is, naturally, a biL unnerving to be faced with all this change 
— to go from being an expert to a beginner The bright side 
(or, I should say, one of the many) is that learning new stuff 
is the fun part, and after you’ve gotten over the shock you'll 
find out that your job just became a whole lot easier, that it s 
a whole lot more fun, and that you're a whole lot more 
productive, 'Hie Carbon API is, refreshingly, more than just a 
compatibility slum on the Classic API — it’s a real step 
forward. If you’re a long-time Mac developer, you'll be glad 
lo see that your took are continuing to evolve, and not just 
change. Although you'll be able to continue developing in 
Carbon for quite a while, and will lx* able to take advantage 
of many of the operating system's new features by doing so, 
I would encourage you to take a serious look at the Cocoa 
API, It is completely different, but if you give it a fair chance, 
you’re going to like it, and you'd be crazy not to use it for 
your new development. If you don't 1 relieve me, than just try 
to find anyone who was ever an OpenStep developer and 
didn’t love it. You won't lx* able to. At the time of writing. 
I’ve just returned from this year's WWDC and during most of 
the WebObjccLs sessions I was struck with just how many 
people, in the midst of voicing a complaint, took the time to 
point out just how much of a joy working with this 
technology is, and to thank the development team. Along 
with an operating system anti a CEO, we've acquired a strong 
community from NeXT, and as we move forward you'll want 
to he a part of it, and to avail yourself of their expertise. 

So what should you do to get “ready for X"? SLep 1 is 
to learn either Objective C or java. C and C++ programmers 
may be a hit irked that they need to learn a new language, 
but iL wilt lx less of a shock that you think, and well worth 

it, (And again, isn't learning a new tool supposed to be ihe 
fun part?) So which one should you use? That's easy — 


either. In fact, learn both, and see which you like best. As 
Mac developers we've always Intel a choice of languages: C, 
C++, Pascal, the BASICS, Perl -— the list goes on. We had 
this range of choice because the Mac API was procedural, 
consisting of structures and functions, and so it was easy to 
access from just about any language —- you just needed the 
right headers or wrappers. The Cocoa API is a framework, 
in the true sense of the word, and frameworks are 
inherently language-specific. So it's rather a miracle that we 
can use Cocoa from both Objective C and Java; they are just 
similar enough under the hood that Apple was able to 
arranged it so that we can use either Cherish this choice— 
it's quite likely the only one well ever have. So learn both 
languages, and if you find that you love one of them and 
hate the other, you should still encourage Apple to support 
both, because choice is a Good Tiling, anti we'll all benefit 
from it in the long run. 

Ah a first step, 1 would encourage you to read Apple’s 
()hject-Oriented Programming and the Objective-C 
Language, even if you don't plan to use Objective C, and 
especially if you are new to object-oriented programming. 
(You can find it online along with the rest of their 
developer documentation J It's relatively short, and the 
introductory material is language neutral and gives an 
excellent explanation of what “OOP" Ls all about. If you're 
a C or C++ programmer, you'll probably find that you can 
pick up Objective C in a couple of hours, assuming you are 
already comfortable with object-oriented concepts. It s just 
a small syntax addition on top of C, and much less of a 
mouthful than C++. It does look a little funny ai first, but 
after you get used ro it. it becomes quite easy to read and 
to work with, (In ease you're wondering, its basic syntax is 
[object message]or '[object message:parameterf, so you'll 
end up with usage which looks like [dog fetch:stick]". This 
syntax is derived from the Smalltalk language, which is the 
“other" famous export of Xerox PARC.) 

Object-Oriented Programming and the Objective-C Language 

<hup://developer.apple,com/techpubs?macosx;Sysrem/ 

DocumenTation/Developer/CocQa/ObjectiveC/ObjC.pdf> 
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Moving beyond the language issue, Apple has 
provided a large amount of documentation on their new 
operating system, and exactly where you should start wall, 
of course, depend on what type of programming you 
actually tin. But there is one general technology which 
you should be sure to familiarize yourself with: Unicode . 

Unicode is not actually new r to the Macintosh 
platform and has been supported long before Mac OS X, 
hut it is used pervasively there and may be new to many 
Mac programmers. In case you haven't encountered it 
before, Unicode is an attempt to create one system which 
can encode all of the characters of all of the languages of 
the world. This is an ambitious goal, but ids necessary if 
first-class information processing is going to make it 
outside of the Western world. Without Unicode, different 
languages are forced to use different encodings, so that a 
byte which represents an in one encoding might 
represent a Thai letter in another, and you have to have 
prior knowledge of the encoding in use if you want to 
make sense of the information. This is problematic, and 
only gets worse if you need to mix characters from 
disparate languages within one document. (On a very 
mundane scale, it also solves the problem that even if you 
think you are only working in ASCII, the Mac OS and 
Windows differ in their encoding of upper-ASCII 
characters, which can cause your curly quotes to turn into 


accented letters.) With Unicode, you will be able to 
faithfully transmit, process, and even display information 
in nearly all languages, even if you can t read it yourself. 
Cocoa uses Unicode internally for all if its string handling, 
and the AT5U1 component of Carbon and Classic allow 
you to manipulate and display it there as well. The 
Unicode Standard itself is available in book form, and a 
much of the surrounding documentation is available on 
the Unicode web site, but this can be a bit overwhelming. 
(The Unicode book itself is quite large, although most of 
it is a listing of the glyphs for the characters.) In fact, you 
really won't need to know most of the details, because the 
system frameworks take care of them for you. but it will 
help to have a basic understanding of the concepts and 
limitations involved. A very useful source for (Ids is the 
newly-published Unicode: A Primer (ISBN: 0-7645-4625- 
2), by Tony Graham, a member of the Unicode 
Consortium, 1 was happy to see that it explicitly mentions 
Unicode support in Mac OS 9 and Mat 1 OS X Server. 

The Unicode Home Page 

<http://www.unicode.org/> 

There are many more interesting technologies 
underpinning Mac OS X, and 1 plan to cover more of them 
in upcoming issues. Until then, get cracking! 101 
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By Richard Atwell, ©2000 by Metrowerks, Inc., all rights reserved 


Arnold goes to WWDC 


Another Worldwide Developer's Conference (WWDC) 
hosted by Apple lias come and gone and once again 
Metrowerks was there in person to meet with you, listen to 
your feedback and converse alxiut the future of Code'Warrior 

This year we sent more engineers than in previous years, 
which was fortunate because attendance this year was at 
record levels and we would have been swamped due to the 
excitement built around the upcoming Mac OS X, 

We were present in the exhibit hall for the first two 
days it was open, as we were last year, and we gave out 
thousands of copies of a special WWDC CD containing a 
beta version of new CodeWarrior tools for Mac OS X. Those 
tools will become pan of CodeWarrior for Mac OS, Version 
6.0. by the time this article hits the stands, the CD will have 
expired and Version 6.0 will be very close to shipping, if it 
hasn't shipped already. 

Last year we had a single keynote event to talk about 
the current state of CodeWarrior, but this year, in addition 
to our booth in the exhibit half w-e hosted and attended 
several sessions, 

Here's an overview of what went down in case you 
missed it. 

Session; Mac OS X THIRD Party Tools 
Presenter: Rerardino Haratta, 

Vice President of Software Engineering 

After Real Basic demonstrated their latest offering 
(written using CodeWarrior, by the way) Berardino gave his 
CodeWarrior state of the union address and showed off the 
latest IDE (IDE 4.1) that will ship with Version 6.0. 

The IDE has been fully Carbonized, as have our support 
libraries, PowerPlant and other development tools like 
Constructor and Profiler. This is our Carbon release for Mac 
OH X developers and the basis for Metrowerks 1 future 
development on the Mac OH platform. 


When running on Mac OS X, the IDE exhibits the 
attractive new Aqua interface. Ifs interesting to note that the 
IDE itself is written with CodeWarrior using PowerPlant, so 
your applications will look “Aquafted” if you use PowerPlant 
as the framework on which to base your application. 

At the end of his session, Berardino answered many 
questions from the audience. Of note, attendees asked about 
Pascal support, Metrowerks didn't ship Pascal tools and 
support libraries for CodeWarrior for Mac OS, Version 5,0 — 
the first time in several releases that we had not. Ai die Lime, 
however, we made a promise to deliver those tools at a later 
dale. Berardino reiterated that promise to update our Pascal 
tools, which will lx; based on Version 6.0 and which will ship 
one last time shortly after Version 6.0 ships. 

Version 6.0 will also be the last release to support 68K 
code generation since Mac OS X only runs on recent 
PowerPC-based Macs, The demand for generating fat binaries 
has dropped dramatically and Berardino stated that after 
Version 6 + 0 those tools will be put into maintenance mode 
and decisions about availability will l>c made at a future date. 

The other popular question was when is Metrowerks 
going to deliver Mach O tools? Hirst, the Version 6.0 CD will 
contain our latest Mach-O plugins in pre-release form. We 
will also provide a command line compiler to substitute for 
the CiCC compiler that ships with Mac OS X. We will follow 
that with support for debugging Mach-O binaries, which 
contain stabs symbolics that run on Mac OH X. 

The BoF (Birds of a Feather) 

Presenters: Tim Freehill, Director of Desktop Products 
and Matt Henderson, Mac OS X Technical I^ad 

Tliis session was our "Birds of a Feather" session. The 
theme was "CodeWarrior is now rated X”. We gave away 
more l>eta CDs, threw T-shirts into the audience and raffled off 
a new' Power!xx>k — so naturally a riot broke out. 


Richard Alexander David Atwell, a.La. H ralwdl,’ works on Metrowerks’ CodeWarrior integrated debugger at the company’s Austin -based 
headquarters. Richard welcomes your feedback and questions on any topic. You can reach him at raLwel 1 ftntet rawer ks . conr 
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Tim was emcee for the evening and introduced Matt, 
who ran through a demonstration of the latest tools. 

Our engineers took questions from the audience and 
after we ran out of shirts and toa CDs we drew the winning 
entry' for the Powerhook. Congratulations to the winner: 
Mark Nelson from the Vancouver Film School. We also gave 
away five three-year subscriptions to CodeWarrior. 

Session: Tuning for MP and Velocity Engine 
Presenters; Bob Campbell, PPC Compiler lead, 

Ken Ryali, Debugger lead Engineer and 
Kiehard Atwell, Mae OS Debugger Engineer 

Velocity Engine is Apple's name for the AltiVec unit tlniL 
is integrated into the Motorola PowerPC 74(X) that ships in 
every PowerMac G4. Bob opened the session with an 
explanation of vector! zation tips that Code Warriors need to 
consider when writing AltiVec code. 

Bob talked about data alignment issues, which affect 
performance and correctness. Many of these concerns are 
taken care of by using our MSI, and runtime libraries, but 
data alignment is always an important consideration since the 
AltiVec unit works best with chunks of 16-byte aligned data. 
Bob went on to explain some features of the AltiVec 
instruction set and ran through a demo of some AltiVec 
enhanced code. The results were compelling: a scalar image 
rotation routine that was highly optimized as scalar code 
processed approximately four mega-pixels per second. The 
AltiVec version using "all the tricks 75 benchmarked at 25 
mega-pixels }>cr second. 

Afterwards, I demonstrated the features of ihe debugger 
that support AltiVec, CodeWarrior displays the individual 
scalar elements of each vector just as the fields of C structures 
are disclosed. To aid with debugging, all elements arc 
editable and are highlighted in red when the values change. 
To support vector editing at the register level, there is a 
new resizable register window that allows you to edit vectors 
in registers as more manageable 32-bit values. Values can be 
viewed as hex or floating point. Just like the variable view, 
as scalars are updated they are highlighted in red to show 
you how the register changed. 

Finally, I demonstrated support for expression 
evaluation using scalar elements and showed how a 
conditional breakpoint could set on a portion of a vector 
register using the vector.[sealari notation that we invented lor 
this purpose. See tlte From the Factory Floor column on 
AltiVec from last year {MacTech Magazine -July, 1999) for a 
complete description of AltiVec support in CodeWarrior, 

Next l presented the multiprocessing (MP) portion of the 
session, I t<x>k the Close ViewMP sample application from the 
Multiprocessing 2.1 SDK and debugged it using the beta Ux>Ls for 
Mac OS X, The Close'ViewMF code makes a good demo because 
it’s visual: die application creates an MP task that continuously 
draws in a window whether you are holding down menus or 
moving windows which would normally hall any live updating 
in tin 1 Ilk Tile window of course runs in the cooperative task. 


Debugger support for Ml 1 lx exists in the Process 
window that shows you llie list of cooperative threads and 
MP tasks 1 relonging to each application. Debugging windows 
appear for each thread or task that generates an exception, 
such as hitting a breakpoint. Just like separate threads, you 
can step through code at any time independent of the state 
of other threads or tasks. Finally, register windows for all 
three register files fGPii f FPR and AltiVec) are available for 
each thread or task and, Lo aid with navigation, the window 
titles indicate which is which. 

Session: Debugging Apes on Mac OS X 
Presenter; Ken Ryali, Lead Debugger Engineer 

This session began wiLh a few demos front Apple and 
Ken followed with a demonstration of single machine 
debugging using the IDE 4,1. 

In Version 5.0 we shipped an early remote debugger for 
Mac OS X. This consisted of the IDE 4.0, ifs preference 
panels and debugging plugins, all of which allowed you to 
remotely debug Carbon-PEF based applications running on 
Mac OS X from an IDE hosting machine running Mac OS 9. 
The other piece of the debugging technology consisted of a 
resident debugging nub, such as MetroNub, that the IDE uses 
to control processes on the target machine, 

Ken demonstrated how to debug a carbonized 
Power Plant sample application from Mac OS X, With this 
level of support, it's possible to debug any combination of 
Mat: OS X anti Mac OS 9 machines. 

Taking tilings a step further, Ken showed a new set of 
panels for remote debug settings. A new remote connections 
panel allows developers to define any set of remote TCP/IP 
connections much like an address book. This change allows the 
IDE to debug remotely or locally at the target level instead of 
running the IDE in one mcxle or the oilier. 

Additional target settings panels allow you to choose which 
remote connection you'd like to use and allow you to specify the 
remote folder where you’d like to debug the target. The panels 
also let you ch<x>se the l< nation of the remote host application 
that will host the shared libraries you'd like to debug. We also 
demonstrated upcoming support to allow you to move support 
files to the machine under remote control. 

See *Ya 

Well that's tt for this WWDC. See you next year. As 
always, visit our newsgroup or send us email directly, 

• Newsgroup: 

comp,sys.mac,programmer.codewarrior 

• Technical Support: 
cw_support@metrowerks.com 

• Report Bugs: 
cw_bug@metmwerk5Xom 

• Suggestions: 

cw_suggestion@metrowerks.com 
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SuSE. 

{soo' sah} is {soo' purb} 


HOW DO YOU SAY 

superb 

IN 

LINuX? 


When you think of Superb, you think of unusually high quality. Like a superb wine, for example. Majestic. 
Rich. Luxurious. Superior. ■ SuSE Linux is all that. And more. More experience. More adaptability. More 
applications—over 1500. ■ More power to you. And more freedom, too. ■ No wonder more than 50,000 
enterprises worldwide bank on its superb open source solutions. Making SuSE the international Linux leader— 
setting a higher standard for excellence, simplicity and support. ■ Even the price is superb. » So, how do you 
say superb in Linux? SuSE. It’s a lesson well learned. 

www.SuSE.com 


Versions for Intel. Alpha, and PowerPC 


The freedom to change. 
The power to change the Linux world. 



SuSE 


© 2WU 5USC All lijpu* rrscjiBl. SuSE* and SuSC kttfu *»* ln*rt«n*rks ol GmbH OUnw riiimw may be liatJeitiarlra at Llmr napcrltw owners. 










Time matters. 

The late of the company is in your hands. 

Every second counts when pure competing at Internet speed. 
And die faster your Web application is developed, deployed and 
maintained, die faster your competition will drop out of sight. 

'Hie solution? Use Pervasive SoftwaresTango 2000 to develop 
your ideas with double the speed of any other development software. 

* Visually develop applications on Mac, ami deploy on 
Mac, Windows, Linux and Solaris 

* Advanced XJvi 1, support 

* Gmnect direedy to Fdemaker or any ODBC; database 

* lixtcnd applications with JavaBeans 

* High performance Tango server scales widi duster support 



Give yourself the same competitive edge that Tango has 
given leading companies like Apple Computet*, rheglobe.com 
and Harhor Freight Tools'". 

Download your Free Tango Demo today! 

Grab the time-saving advantages of Tango 2000 absolutely 
FREE Visit our Web site and download our FREE folly functional 
iango 2000 demo. Or call lls now to get your demo on CD. 

www.pervasive.cani/speed or 1-800-287-4383 

I lurry! This ofter ends soon. 


PERVASIVE 

\SOFTWAft£ 

The Freedom to Create Application^ 
for Eyeryoae, Every whe 


***** Compiftef fe5 a register-wf rfatfetnart; pi Aw>le Compute* Inn.. ih«^tet*.awn 15 a nadomartc of thegtoba.uorti, Inc., Harbor freight Toofa Is a imriamR/fc oi Martwr freight |bois. ,, 










